Setting up IBM Cloud App ID with your Azure Active Directory

5 min read

Setting up IBM Cloud App ID with your Azure Active Directory

Last week we launched our newest IBM Cloud App ID feature, SAML 2.0 Federation. This feature allows you to easily manage user identities in your B2E apps while authenticating the users using existing enterprise flows and certified user repositories. In this blog we will use Azure Active Directory as an example identity provider and show how a developer can configure both App ID and Azure Active Directory so that:

  • Active Directory authenticates app users

  • App ID federates and manages user identities

App ID allows developers to easily add authentication, authorization and user profile services to apps and APIs running on IBM Cloud. With App ID SDKs and APIs, you can get a sign-in flow working in minutes, enable social log-in through Google and Facebook, and add email/password sign-in. The App ID User Profilesfeature can be used to store information about your users, such as their app preferences. In short, App ID enables your app to be used only by authorized users and that authorized users have access to only what they should have access to. The app experience is custompersonalized and most importantly, secure.

SAML 2.0 Federation Architecture

Before we begin, we should first review the architecture and flow of a federation based enterprise login and SSO using the SAML 2.0 framework. Here, Active Directory is the identity provider that provides enterprise identity and access management (IAM).

Federation-based enterprise login and SSO using SAML 2.0

Federation-based enterprise login and SSO using SAML 2.0

  1. Application user opens an application deployed on cloud or invokes a protected cloud API.

  2. App ID automatically redirects the user to the Enterprise IAM identity provider.

  3. The user is challenged to sign-in using enterprise credentials and familiar UI/UX.

  4. On successful login Enterprise IAM identity provider redirects user back supplying SAML assertions.

  5. App ID creates access and identity tokens representing user’s authorization and authentication and returns them to the application.

  6. Application reads the tokens to make business decisions as well as invoke downstream protected resources.

Configuration Steps

Before we begin:

You must have:

  • An IBM Cloud account and logged on through a browser

  • Created an App ID instance

  • Setup an Azure account with Active Directory service

Step 1

Sign in to your IBM Cloud, browse to the catalog and create an App ID instance. Under the Identity Providersmenu, select SAML 2.0 Federation.

SAML 2.0 Federation


Step 2

Click on the Download SAML Metadata file. This will download a file appid-metadata.xml.

Download SAML Metadata file


Let’s review some of parameters defined in the metadata file. We need these parameters to configure the identity provider. 

  • <EntityDescriptor> identifies the application for which the SAML identity provider is being setup. EntityID is the unique identifier of the application.

  • <SPSSODescriptor> describes the service provider (SP) requirements. App ID requires the protocol to be SAML 2.0. The service provider must sign its assertions.

  • <NameIDFormat> defines how App ID and the identity provider uniquely identity subjects. In this case, App ID uses emailAddress and therefore the identity provider needs to associate username with emailAddress.

  • <AssertionConsumerService> describes the protocol and endpoint where the application expects to receive the authentication token.

You can find more detailed documentation on both mandatory and optional attributes that App ID supports here.

Step 3

Sign into the Azure portal using your administrator account, and browse to the Active Directory > Enterprise Applications > New application > Non-gallery application section, select Add, and then Add an application from the gallery. In the app gallery, add an unlisted app by selecting the Non-gallery application tile. Enter a Name for your application.

Azure portal


Step 4

You can now configure the single sign-on options and behavior for your application on Azure AD.

Step 4.1

Select Configure single sign-on (required) option.

Step 4.2

Extract the AppIDConsumer Domain and URLs from the App ID metadata file `appid-metadata.xml`

  • Identifier: This is the Entity ID value from appid-metadata.xml.

  • Reply URL: This is the Assertion Consumer Service (ACS) URL value from appid-metadata.xml.

  • User Identifier: Select

Save the configuration.

Download SAML Metadata file


Azure portal


Step 4.3

App ID supports name , email , picture and locale  custom attributes in the SAML assertions it receives from the identity provider. App ID can only consume these attributes if they are in the following format:

<Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="name"><AttributeValue>Ada Lovelace</AttributeValue></Attribute>

NameFormat is the way that App ID interprets the Name field. The format specified urn:oasis:names:tc:SAML:2.0:attrname-format:basic is also the default format if no format is provided.

Active Directory does not have these attribute mapping by default. You can add these by checking the field View and edit all other user attributes. You will notice that Active Directory already has several attributed pre-defined, but these are not in the format that App ID expects and therefore App ID ignores them in the SAML response. Custom attributes can be defined by going to Add Attribute and choosing  one of the attribute names App ID supports (such as name or picture), choosing the right Azure attribute from the drop down menu and finally pasting the name format for Namespace field.

Add Attribute


You can set up a custom mapping for each of the App ID expected attributes in a similar manner.


Step 4.4

Click on Configure Your Application to obtain the values needed to configure Active Directory as the identity provider of App ID. You will also need to download the SAML Signing Certificate (Base64 encoded), which is a PEM encoded certificate that you will need for configuring App ID.

Configure Your Application


Step 5

You can now finish configuring the App ID instance. 

  • entityID: Copied from SAML Entity ID field from Step 4.4

  • Sign-in URL: Copied from SAML Single Sign-On Service URL field from Step 4.4

  • Primary Certificate: Copied from SAML Signing Certificate – Base64 encoded from Step 4.4

Save your configuration.

Step 6

You can now test your configuration by clicking on the Test button. This will initiate an authentication request to Active Directory. Make sure you have saved your configuration before testing, otherwise Test will not work. 



Once you have entered the credential information and successfully authenticated with Active Directory, you should be presented with an App ID access token as well as an identity token.




You have successfully configured your App ID instance using an Azure Active Directory!

Make sure you check out some of our upcoming blog articles in our App ID SAML series:

  • Setting up IBM Cloud App ID with your Active Directory Federation Service

  • Setting up IBM Cloud App ID with Ping One

Questions and feedback

  • If you have technical questions about App ID, post your question on Stack Overflow and tag your question with ibm-appid.
  • For questions about the service and getting started instructions, use the IBM Developer Answers forum. Include the appid tag.
  • Open a support ticket in the IBM Cloud menu.
  • Reach out directly to the development team on Slack!

To get started with App ID, check it out in the IBM Cloud Catalog.


Be the first to hear about news, product updates, and innovation from IBM Cloud