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

By: Gelareh Taban

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 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, AD FS 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 a local AD FS server

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.

SAML 2.0 Federation

 

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 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

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… .

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.

Step 4

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 Address to a similarly named outgoing claim type.

    • Give the rule a name such as LDAP Email rule

    • Set Attribute Store to Active Directory

    • Create a map between E-mail Address to E-mail Address

    • Click OK

Edit Claim Issuance Policy for App ID

 

  • 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

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Send Claims Using a Custom Rule

 

Step 5

App ID also 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.

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

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("name"), query = ";displayName;{0}", param = c.Value);

 

Similar rules can be added for emailpicture, and locale attributes.

Step 6

You now need to obtain the AD FS metadata file  to finish configuring your App ID instance.

Step 6.1

You must first locate the file URL:

  • Open the AD FS management console

  • In the AD FS folder, expand Services and click Endpoints.

  • Locate the FederationMetadata.xml file.

Endpoints

Step 6.2

Use a browser to navigate to that URL on the ADFS server and download the file. For example, https://https://localhost/FederationMetadata/2007-06/FederationMetadata.xml

Step 7

Finish configuring App ID by using the information in FederationMetadata.xml. 

  • Set entityID to the attribute of the same name from the metadata file.

  • Set Sign-in URL to the URL value for the SingleSignOnService attribute in the metadata file.

  • Primary Certificate should be set to the base64 encoded signing certificate string located under KeyDescriptor use="signing"

Save the configuration data.

Step 8

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.

Congratulations!!

Congratulations!!

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

Try it out!

We’d love to hear from you with feedback and questions. Get help for technical questions at Stack Overflow, with the ibm-appid tag. For non technical questions, use IBM developerWorks, with the appid tag. For defect or support needs, use the support section in the IBM Cloud menu.

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