Security

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

Share this post:

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 Profiles feature 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).

Architecture of SAML Federation using App ID and a SAML 2.0 Identity Provider

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 Providers menu, select SAML 2.0 Federation

 

Create an App ID instance for AD FS.

 

Step 2

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

 

appid.xml

 

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

 

 

  • 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

Add Email Attribute to AD FS

 

  • 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");

Add Custom Attribute to AD FS

 

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 email, picture, 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.

 

AD FS metadata gile

 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.

 

Successful test of AD FS connection

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

 

More Security stories
December 10, 2018

IBM Cloud Security Advisor Now Integrates to NeuVector’s Kubernetes Security Platform

Today, we are excited to further strengthen the relationship between IBM Cloud and NeuVector by announcing the integration of Security Advisor and the NeuVector container network security solution. We have integrated your IBM Cloud security tools into one dashboard and console to facilitate centralized security management for the security admin.

Continue reading

November 16, 2018

iExec Integrates IBM Cloud to Increase the Security of Decentralized Computing

Empowered by the unique IBM Cloud approach to cloud security, iExec is extending the value of cloud by helping enterprises run even their most sensitive workloads on shared hardware at much lower risk.

Continue reading

November 7, 2018

New in App ID: App Identity, Custom Sign-In Methods, and More

With the new capabilities in IBM Cloud App ID, you can now leverage any custom identity provider or sign-in method and authenticate apps in addition to users.

Continue reading