Community

Converting Your Applications from IBM Single Sign-On service to IBM Cloud App ID

Share this post:

On March 30th, 2018 IBM has announced the deprecation of IBM Single Sign-On service. The service will remain available for provisioning for 30 days after which it will be removed from the IBM Cloud Catalog. Existing instances of the service will continue to be operational and supported for 12 month. During this time you need to convert your applications to use newly provisioned instances of IBM Cloud App ID service. The goal of this blog is to guide you through the application conversion process.

IBM Cloud App ID is the strategic identity service on IBM Cloud. Use it to add authentication to your mobile and web apps and protect your APIs and back-ends running on IBM Cloud. Enable email/password based sign-up and sign-in with Cloud Directory – App ID’s scalable user registry, allow your employees to sign-in with their existing credentials via SAML federation, or use social sign-in with Facebook and Google. Host user profile info that you can use to build engaging experiences. IBM Cloud App ID is a cloud-native, managed service running in multiple regions and availability zones of IBM Cloud, providing data governance, access management, and other capabilities. App ID’s graduated tier pricing is described here.

App ID provides the core functionality of the Single Sign-On service, such as enterprise and social identity provider federation and cloud directory, as well as many additional capabilities, such as mobile and server SDKs, public Swagger-documented APIs, user profiles, progressive authentication, customizable Login Widget and much more.

At the moment of writing this article, the IBM Cloud App ID service is available in us-south (Dallas), eu-gb (London), eu-de (Frankfurt) and au-syd (Sydney) regions running in multi-availability-zone environments.

Conversion framework

In order to facilitate the conversion from now-deprecated IBM Single Sign-On service to the IBM Cloud App ID service we’re providing the below conversion guide. In most cases you will need to perform two mandatory and one optional steps:

  • Configuring identity providers
  • Updating application protection
  • [Optional] Updating application business logic

We’ll go through each of these steps in detail below.

Note that while IBM Single Sign-On service was primarily targeting SSO capabilities for web application , the App ID provides both authentication and authorization capabilities. After converting your applications to use App ID you will get both id_token with user identity information and access_token with information about user authorization. Moreover, App ID allows applications to use access_token to make requests to backend resources protected by App ID authorization filters. These and many other capabilities of App ID are out of scope of this conversion framework since they’re unique to App ID. Still, we do highly encourage you to get acquainted with them by going through App ID documentation and reading the App ID White Paper.

Step 1 – Configuring Identity Providers
Similar to the Single Sign-On service the first steps to start using App ID would be provisioning a service instance and configuring the identity providers. Out-of-the-box App ID supports Enterprise identity federation with SAML, Cloud Directory – a user repository hosted in your App ID instance, and social identity provider federation for Facebook and Google.

In order to provision an instance of App ID navigate to the IBM Cloud Catalog and search for App ID. Pick region and a resource group you want to provision App ID in and click CREATE. Creating an instance of App ID takes just a few seconds, and once it is created you’ll be taken to a Getting Started screen. We highly encourage developers to go through the Getting Started to get a better understanding of App ID workflows as well as downloading and running a few sample apps.

Enterprise Identity Federation with SAML Identity Providers:
SAML is an open standard for exchanging authentication and authorization data between an identity provider who asserts the user identity and a service provider who consumes the user identity information. App ID functions as a service provider and initiates a single sign on (SSO) login to a third-party provider such as Active Directory Federation Services. The SAML protocol supports different profiles and bind options. App ID supports the web browser SSO profile, with HTTP Post binding. If you were using Enterprise identity federation with SAML you’ll need to start by adding a new service provider configuration to your SAML identity provider. The process of configuring App ID with SAML identity provider is described in detail here. In addition we’ve published a set of blogs explaining how to configure Enterprise identity federation with several most common identity providers such as Active Directory Federation ServicePing Identity, and Azure Active Directory.

Once you’ve configured your Enterprise identity federation with SAML you can test the configuration with the TEST button available in the App ID dashboard.

Cloud Directory:
Cloud Directory is a highly scalable, cloud-hosted user repository that you can use to store user records. Both Single Sign-On and App ID provide this feature, so depending on number of users you might to either manually recreate the user accounts or consider data migration. At the moment we’re planning to provide a data migration path in future, subscribe to IBM Cloud Blogs for additional updates.

Social Identity Providers:
When you provision an instance of App ID the social identity providers, such as Facebook and Google, are enabled and pre-configured with App ID development credentials by default. This means that you can start experimenting with your App ID instance right away, without any additional configuration. Once you feel you’re ready to take your application to the next stage you’ll need to update social identity providers credentials with real client_id and secret of your Facebook/Google application as described in documentation.

Step 2 – Updating application protection
Both Single Sign-On and App ID services employ similar approach to protecting web applications. Node.js applications are protected using passport.js strategies, Liberty applications are protected using the built-in OIDC Client feature. Therefore converting applications from using Single Sign-On to App ID should be straight-forward for developers. Note that Single Sign-On service only supported Cloud Foundry applications bound to the service instance. App ID does not have this limitation, it supports any kind of application runtime environment – Cloud Foundry, Kubernetes, locahost etc.

Converting Node.js applications
With the Single Sign-On service you were required to use the passport-idaas-openidconnect npm module. The module was initialized with credentials obtained from VCAP_SERVICES environment variable provided by Cloud Foundry. Once an instance of IDaaSOIDCStrategy was initialized you’ve used it with passport.js to protect your web applications. The whole process is described in detail here.

App ID provides a similar approach. You need to add the bluemix-appid npm module to your application by running ‘npm install –save bluemix-appid’. The bluemix-appid module provides two types of strategies – APIStrategy, which is used to protect APIs, and WebAppStrategy, which is used to protect Web applications. Create an instance of WebAppStrategy to protect your web application and use it with passport.js similar to the way you’ve used passport-idaas-openidconnect.

const WebAppStrategy = require(‘bluemix-appid’).WebAppStrategy;
// your app initialization code
passport.use(new WebAppStrategy({
    tenantId: “{tenant-id}”,
    clientId: “{client-id}”,
    secret: “{secret}”,
    oauthServerUrl: “{oauth-server-url}”,
    redirectUri: “{app-url}” + CALLBACK_URL
}));

There are some subtle but important differences to be aware of. One such differences is the way SDK is initialized. You can either specify initialization credentials manually, similarly to the way you’ve used passport-idaas-openidconnect, or omit the initialization parameters. In the latter case the bluemix-appid module will try to retrieve credentials automatically from the environment. In any case – after initialization you will see console log output describing whether credentials were successfully obtained.

Similarly to the Single Sign-On service you’ll need to define login, callback, and optionally logout endpoints in your application.

app.get(LOGIN_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
    successRedirect: LANDING_PAGE_URL,
    forceLogin: true
}));

app.get(CALLBACK_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME));

app.get(LOGOUT_URL, function(req, res){
    WebAppStrategy.logout(req);
    res.redirect(LANDING_PAGE_URL);
});

For additional details on how to instrument your Node.js web application with App ID see the readme file in the SDK github.com repo and App ID documentation

Converting Liberty for Java applications
Both Single Sign-On and App ID use similar approach for Liberty for Java applications – OpenID Connect feature of Liberty services. Start by ensuring that your Liberty server configured to use the required features in server.xml

<featureManager>
    <feature>openidConnectClient-1.0</feature>
    <feature>ssl-1.0</feature>
    <feature>appSecurity-2.0</feature>
    …… other features ……
</featureManager>

Next step is to update the OpenID Connect client configuration in server.xml file to contain the credentials of your App ID instance:

<openidConnectClient
    id=’${cloud.services.appid.connection.clientId}’
    clientId=’${cloud.services.appid.connection.clientId}’
    clientSecret=’${cloud.services.appid.connection.secret}’
    authorizationEndpointUrl=’${cloud.services.appid.connection.authorizationEndpointUrl}’
    tokenEndpointUrl=’${cloud.services.appid.connection.tokenEndpointUrl}’
    jwkEndpointUrl=’${cloud.services.appid.credentials.jwkEndpointUrl}’
    redirectToRPHostAndPort=’http[s]://your-application-url’
    issuerIdentifier=”appid-oauth.ng.bluemix.net”
    tokenEndpointAuthMethod=”basic”
    signatureAlgorithm=”RS256″
    httpsRequired=’true/false’ />
<keyStore id=”defaultKeyStore” password=”changeit” type=”jks” location=”${java.home}/lib/security/cacerts”/>

Where the values of clientId, clientSecret, authorizationEndpointUrl, tokenEndpointUrl are obtained from your App ID service instance credentials. The value of jwkEndpointUrl is the value of authorizationEndpointUrl with “/publickeys” at the end.

Make sure that the <application> component in your server.xml has the definition of application binding to a security role

<application-bnd>
    <security-role name=”myrole”>
        <special-subject type=”ALL_AUTHENTICATED_USERS”/>
    </security-role>
</application-bnd>

The last part is making sure that the security role you’re using in your server.xml file is also defined in the security constrains section of your web.xml

<security-constraint>
    <display-name>liberty-webapp-security-constraint</display-name>
    <web-resource-collection>
        <web-resource-name>homepage</web-resource-name>
        <url-pattern>/</url-pattern>
        <url-pattern>/*</url-pattern>
        <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
        <role-name>myrole</role-name>
    </auth-constraint>
    <user-data-constraint>
        <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
</security-constraint>

For additional details on how to instrument your Liberty for Java application with App ID see the App ID documentation.

Step 3 – Updating Application Business Logic
This step is optional, it is only required if your applications are leveraging the user information obtained from Single Sign-On id_token. While both Single Sign-On and App ID service provide id_tokens, the structure of this tokens has minor differences. Depending whether you’re using particular claims from these tokens you must need to update your application code. For example, both services provide email addresses as part of id_token, however Single Sign-On claim name is “emailAddress” and App ID claim name is “email”. Below see the list of claims provided by both services

Information 
Single Sign-On Claim
App ID claim
Description
Issuer
iss
iss
Issuer of the token, the App ID server URL
Tenant
N/A
tenant
The App ID instance ID (a.k.a tenant ID)
Subject
sub
sub
Unique subject identified in the service instance
Audience
aud
aud
The intended consumer of the token, usually client_id of the relying party
Issued at
iat
iat
The issuance time of the ID token. The time is expressed in UNIX time stamp format
Expiration
exp
exp
Expiry time of the ID token. The time is expressed in UNIX time stamp format
First Name
firstName
N/A
User’s first name
Last Name
lastName
N/A
User’s last name
Display Name
displayName
name
User’s full name as reported by identity provider
Locale
N/A
locale
User’s locale as reported by identity provider (if available)
Picture
N/A
picture
URL to user’s profile picture as reported by identity provider (if available)
The login method
realmName
amr
The login method used. The value varies depending on the type of identity provider
Email
emailAddress
email
User’s email
OAuth Client
N/A
oauth_client
Information about OAuth client (device/application) used to obtain this token
See additional information about id_token structures for Single Sign-On service, App ID service.

IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM’s sole discretion. Information regarding potential future products is intended to outline our general product direction and it should not be relied on in making a purchasing decision. The information mentioned regarding potential future products is not a commitment, promise, or legal obligation to deliver any material, code or functionality. Information about potential future products may not be incorporated into any contract. The development, release, and timing of any future features or functionality described for our products remains at our sole discretion.

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 Community stories
October 10, 2018

Growth Fabric – Learnings for Repeatable Growth

If mastering growth isn't already challenging enough, how do we ensure it's repeatable? We've got five steps to ensure that your robust efforts to create or transform yourself and your organization into a growth juggernaut are not lost the moment that something changes.

Continue reading

August 3, 2018

Five Exciting Things About Istio v1.0

Istio, an open platform to connect, secure, control, and observe microservices, was launched on May 24, 2017, with joint force by IBM, Google, and Lyft. Over the last year, numerous new features and improvements have been made to get to the current production-ready version 1.0.

Continue reading