To use App ID for user authentication for IBM watsonx, you configure App ID as a service on IBM Cloud. You configure an identity provider (IdP) such as Azure Active Directory. You then configure App ID and the identity provider to communicate with each other to grant access to authorized users.
To configure App ID and your identity provider to work together, follow these steps:
- Configure your identity provider to communicate with IBM Cloud
- Configure App ID to communicate with your identify provider
- Configure IAM to enable login through your identity provider
Configuring your identity provider
To configure your identity provider to communicate with IBM Cloud, you enter the entityID and Location into your SAML configuration for your identity provider. An overview of the steps for configuring Azure Active Directory is provided as an example. Refer to the documentation for your identity provider for detailed instructions for its platform.
The prerequisites for configuring App ID with an identity provider are:
- An IBM Cloud account
- An App ID instance
- An identity provider, for example, Azure Active Directory
To configure your identity provider for SAML-based single sign-on:
1. Download the SAML metadata file from App ID to find the values for entityID and Location. These values are entered into the identity provider configuration screen to establish communication with App ID on IBM Cloud. (The corresponding values from the identity provider, plus the primary certificate, are entered in App ID. See Configuring App ID).
- In App ID, choose Identity providers > SAML 2.0 federation.
- Download the appid-metadata.xml file.
- Find the values for entityID and Location.
2. Copy the values for entityID and Location from the SAML metadata file and paste them into the corresponding fields on your identity provider. For Azure Active Directory, the fields are located in Section 1: Basic SAML Configuration in the Enterprise applications configuration screen.
| App ID value | Active Directory field | Example |
|---|---|---|
| entityID | Identifier (Entity ID) | urn:ibm:cloud:services:appid:value |
| Location | Reply URL (Assertion Consumer Service URL) | https://us-south.appid.cloud.ibm.com/saml2/v1/value/login-acs |
3. In Section 2: Attributes & Claims for Azure Active Directory, you map the username parameter to user.mail to identify the users by their unique email address. IBM watsonx requires that you set username to the user.mail attribute. For other identity providers, a similar field that uniquely identifies users must be mapped to user.mail.
Configuring App ID
You establish communication between App ID and your identity provider by entering the SAML values from the identity provider into the corresponding App ID fields. An example is provided for configuring App ID to communicate with an Active Directory Enterprise Application.
1. Choose Identity providers > SAML 2.0 federation and complete the Provide metadata from SAML IdP section.
2. Download the Base64 certificate from Section 3: SAML Certificates in Active Directory (or your identity provider) and paste it into the Primary certificate field.
3. Copy the values from Section 4: Set up your-enterprise-application in Active Directory into the corresponding fields in Provide metadata from SAML IdP in IBM App ID.
| App ID field | Value from Active Directory |
|---|---|
| Entity ID | Azure AD Identifier |
| Sign in URL | Login URL |
| Primary certificate | Certificate (Base64) |
4. Click Test on the App ID page to test that App ID can connect to the identity provider. The happy face response indicates that App ID can communicate with the identity provider.
Configuring IAM
You must assign the appropriate role to the users in IBM Cloud IAM and also configure your identity provider in IAM. Users require at least the Viewer role for All Identity and IAM enabled services.
Create an identity provider reference in IBM Cloud IAM
Create an identity provider reference to connect your external repository to your IBM Cloud account.
- Navigate to Manage > Access(IAM) > Identity providers.
- For the type, choose IBM Cloud App ID.
- Click Create.
- Enter a name for the identity provider.
- Select the App ID service instance.
- Select how to on board users. Static adds users when they log in for the first time.
- Enable the identity provider for logging in by checking the Enable for account login? box.
- If you have more than one identity providers, set the identity provider as the default by checking the box.
- Click Create.
Change the App ID login alias
A login alias is generated for App ID. Users enter the alias when logging on to IBM Cloud. You can change the default alias string to be easier to remember.
- Navigate to Manage > Access(IAM) > Identity providers.
- Select IBM Cloud App ID as the type.
- Edit the Default IdP URL to make it simpler. For example,
https://cloud.ibm.com/authorize/540f5scc241a24a70513961can be changed tohttps://cloud.ibm.com/authorize/my-company. Users log in with the alias my-company instead of 540f5scc241a24a70513961.
Learn more
- IBM Cloud docs: Managing authentication
- IBM Cloud docs: Configuring federated identity providers: SAML
- IBM Cloud docs: Which SAML federation options exist in IBM Cloud?
- Setting up IBM Cloud App ID with your Azure Active Directory
- Reusing Existing Red Hat SSO and Keycloak for Applications That Run on IBM Cloud with App ID
Parent topic: Setting up IBM Cloud App ID (beta)