Setting up IBM Cloud App ID with your Active Directory Federation Service
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 a private Active Directory Federation Service (AD FS) so that:
AD FS 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 custom, personalized 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, AD FS is the identity provider that provides enterprise identity and access management (IAM).
Federation-based enterprise login and SSO using SAML 2.0
Application user opens an application deployed on cloud or invokes a protected cloud API.
App ID automatically redirects the user to the Enterprise IAM identity provider.
The user is challenged to sign-in using enterprise credentials and familiar UI/UX.
On successful login Enterprise IAM identity provider redirects user back supplying SAML assertions.
App ID creates access and identity tokens representing user’s authorization and authentication and returns them to the application.
Application reads the tokens to make business decisions as well as invoke downstream protected resources.
Before we begin:
You must have:
An IBM Cloud account and logged on through a browser
Created an App ID instance
Setup a local AD FS server
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.
Click on the Download SAML Metadata file. This will download a 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. App ID uses emailAddress and therefore the identity provider needs to associate
<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.
Open the AD FS Management application. To create a relying party trust instance, open the wizard by selecting Relying Party Trusts > Add Relying Party Trust… .
Select Claims Aware type of application.
Select Import data about relying party from a file and browse to where you saved the App ID metadata file.
Set your Display Name and Access Control Policy and Click Finish.
On the last page, you have the option of configuring your custom claims policy by choose Configure claims issuance policy for this application. This wizard can also be opened independently. Step 4 will cover what custom attributes we can set and how to set them.
AppID expects all SAML Responses to include a NameID attribute which is used by App ID and the identity provider to uniquely identity subjects. This attribute much also conform to the format specified by App ID’s metadata file (in Step 2). To set up this mapping in AD FS, a custom rule must be set.
Open the Edit Claim Issuance Policy for App ID wizard and add the following rules.
Your first claim rule template should be Send LDAP Attribute as Claims. This claim will map the AD attribute
Email Addressto a similarly named outgoing claim type.
Give the rule a name such as
LDAP Email rule
Set Attribute Store to
Create a map between
Your second claim rule template should be Send Claims Using a Custom Rule. This claim will create a NameID or a unique identifier in the format App ID expects.
Name the rule
Custom email rule
Copy and paste the following custom rule and then click OK
App ID also supports
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:
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.
To add these additional rules, open the Edit Claim Issuance Policy for App ID wizard and add the following rule(s).
Your claim rule template should be Send Claims Using a Custom Rule. This claim will create a NameID or a unique identifier in the format App ID expects.
Name the rule
Custom name rule
Copy and paste the following custom rule and then click OK
Similar rules can be added for
You now need to obtain the AD FS metadata file to finish configuring your App ID instance.
You must first locate the file URL:
Open the AD FS management console
In the AD FS folder, expand Services and click Endpoints.
Use a browser to navigate to that URL on the ADFS server and download the file. For example,
Finish configuring App ID by using the information in
entityIDto the attribute of the same name from the metadata file.
Sign-in URLto the URL value for the
SingleSignOnServiceattribute in the metadata file.
Primary Certificateshould be set to the base64 encoded signing certificate string located under
Save the configuration data.
You can now test your configuration by clicking on the Test button. This will initiate an authentication request to your AD FS and open familiar authentication UI/UX. 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 AD FS, 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 Active Directory Federation Service!
Make sure you check out some of our upcoming blog articles in our App ID SAML series:
Setting up IBM Cloud App ID with Azure Active Directory
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.