Self-service identity federation to an IBM Cloud Account with Okta

Although there is generic SAML identity integration examples provided in the AppID documentation, how to specifically configure a particular identity provider in a step-by-step manner can be non-trivial, especially for SAML. In general the approach is to configure SAML identity providers to work with App ID by providing metadata from App ID to your identity provider, and metadata from your identity provider to App ID.

This quick guide will provide tips on configuring access to Okta managed identities to an IBM Cloud Account by performing the following steps:

Adding an IBM Cloud Access Group with a policy for the users
Add an IBM AppID service instance (lite plan used in the case)
Configure a SAML application in Okta (can be done in a trial/developer account, however a similar process will apply for any Okta account)
Complete configuring the SAML identity provider in AppID
Enabling external authentication using AppID
Authorizing Federated Identity users to an Access Group

Optional configuration options

Configure IdP initiated login
Dynamic access group assignment from Okta groups

Adding an IBM Cloud Access Group with a policy

For this example, the Access Group will be configured to access Cloud Object Storage resources in the default resource group in the account. In practice, one or more groups with policies for the necessary resources/services for the organization team(s) will be created. Creating these is outside of the scope of this guide.

Sign in to IBM Cloud and open the Access groups panel.
Click on the Create button and provide a name for the group like COS-demo, provide a description if desired and then click the Create button.
In the group view, select the Access tab and click on Assign access.
Define the policy - Select Cloud Object Storage as the Service, for Resources, select Specific resources and define a condition on Resource group attribute specifying default (or Default, whichever is present). For Resource group access, select Viewer and for service Roles and actions, select Writer as the service access and Operator as the platform access. Skip setting Conditions. When done the policy will look like:
Click on the Add button, and then click on Assign on the right panel to assign the policy to the Access Group

If needed, it is possible to add multiple policies by repeating the steps above until all policies have been created and then clicking on Assign
This is an extra step that is not needed.

Add an IBM AppID service instance

Create an instance of AppID from the catalog. Selecting the lite plan for the service instance is sufficient for many scenarios of Identity Federation ( includes 1000 events and up to 1000 users ). Provide a service name and target resource group and any resource tags if desired.

After the instance is created, open up the service control panel and select Manage Authentication. For this use case, disable all Identity providers (e.g. Cloud Directory, Facebook, Google...). The SAML provider cannot be enabled until it is configured. Begin the configuration by selecting Edit for the SAML item.

Put in a provider name - like Okta, then click on the Download SAML metadata file to get the metadata needed to provide to Okta to configure the connection with the AppID instance. Make a note of the location of the file as it will be used in the next step.

Configure a SAML application in Okta

For this phase, you will define a new Okta application that will provide authentication services for the IBM AppID service, using the metadata provided when the provider was defined in the previous step.

Using an Okta account (sign up a developer account here if you don't have one), expand the Applications->Applications item from the left menu. Select the Create App Integration option:
Select SAML 2.0 option and click on Next
Provide a meaningful name like IBM Cloud AppID, add a logo if desired and click on Next . note - There needs to be a unique Okta Application for each AppID instance that will be using Okta as an identity provider so in some cases it may be appropriate to append the IBM Cloud Account ID number to the name.
Open the metadata file saved in the previous step in order to get entries to use for the SAML Settings.
Copy the Location atttribute from the <AssertionConsumerService\> tag to the Single sign-on URL field. This is a URL like https://us-south.appid.cloud.ibm.com/saml2/v1/2834baa2-f788-4416-a0a4-994e3207932e/login-acs
Copy the entityID attribute from the <EntityDescriptor> tag to the Audience URI field.
Set the Name ID format to EmailAddress.
For Application username select Email. In some cases it may be ok to use Okta username.
There are no modifications needed in the Advanced Settings.
In most cases, it is correct to add additional attributes as follows:

Name Name Format Value

username Basic user.login

firstname Basic user.firstName

lastname Basic user.lastName
Click on Preview the SAML Assertion to see what will be sent from Okta to AppID.
Click on Next and then Finish (the last panel page is optional) to see the metadata that is needed to provide to AppID to complete the SAML Federation configuration.
Now is a good time to add at least 1 test user to the Okta application in order to successfully test the AppID SAML Federation configuration.

Name	Name Format	Value
username	Basic	user.login
firstname	Basic	user.firstName
lastname	Basic	user.lastName

Complete configuring the SAML identity provider in AppID

When you initially definied the SAML IdP in AppID and obtained the metadata, there were a number of fields on the right side of the pane that are empty. Only three of these need data from Okta to complete the configuration.

In the SAML 2.0 panel, click on More details to display specifics of the Identity Provider.
Copy the Sign on URL in Okta to the Sign in URL field in AppID
Copy the Issuer in Okta to the Entity ID field in AppID
Finally - select the Copy link for the Signing Certificate item and paste this into the Primary certificate field in AppID.

The AppID SAML 2.0 Federation configuration panel should look like this:

Click on the Test button and confirm that authentication to Okta is successful. Then click on Save before proceeding.

For the test to succeed, the user associated with the Okta id being tested needs to be added to the application (or a group that they are a member of needs to be added to the application). The details of this will vary by organization and is not covered here.

Important - after saving the configuration, go back to the Manage Authentication panel in AppID and enable the SAML 2.0 Federation provider:

Enabling external authentication using AppID

This section follows steps from the documentation using options that have been tested with Okta.

In the IBM Cloud console, go to Manage > Access (IAM) > Identity providers
Make a note of the Default IdP URL that is shown. Optionally, the string at the end can be modified, but it does need to be a unique string. This is the URL where users will go to authenticate to IBM Cloud through the Okta IdP
Click on Create to define the IdP
Provide a name (for example: Okta)
Use the pull-down to select your AppID service instance
Select Static as the option to onboard users (further testing needs to be performed to update this guide for dynamic mapping)
Keep both Enable for account login and Set as the default selected.
Click on Create, if a success message is displayed, then the IdP is ready to be used.
Copy the Default IdP URL into a new browser session - this should browser session should not be the same context as the current IBMid user that is logged in to IBM Cloud. Either use a different browser or an incognito/private session). Complete the sign-in via Okta.

If the login is successful, the user from the IdP will be added to the Account and be visible in the Manage > Access (IAM) > Users

Authorizing Federated Identity users to an Access Group

Once a Federated Identity user is added to the account, they need to be associated with access groups. This can done in many ways including using UI, CLI or terraform (to manage the users in the access group). For simplicity, this guide will cover the process in the UI.

As an IBM Cloud user with IAM management permissions in the account (including Administrator platform role for the resource group and any service instances set in the policies of the Access Group), open Manage > Access (IAM) > Users and select the onboarded user.
On the Access tab, note that the user is shown as a member of the Public Access group only. This allows the user to log in to the account, but not see any resources within the account.
Click on Assign group and select the COS-demo group that was created initially, then click on Add followed by Assign.
Done! Now when the user views the Resource list in the console, they will see the Cloud Object Storage instance and be able to open the control panel, browse buckets, etc.

Configure IdP initiated login

In some cases, it may be preferred to have end-users access applications through their Identity Provider Dashboard which lists all of the applications that the user is enrolled to access. This can be configured by adjusting the configuration of the SAML 2.0 Federation Identity Provider in AppID. To configure this follow these steps:

Open the AppID instance and the SAML 2.0 Federation identity provider configuration panel.
On the right hand side under Provide metadata from SAML IdP, enable the toggle below the certificate section for IdP initiated login.
Enter in the Default IdP URL from the Manage > Access (IAM) > Identity providers page.
Click on Save to apply the URL

At this point, users should be able to click on the "IBM Cloud AppID" (or whatever the application was named in Okta) app item in their dashboard to initiate the login process to the IBM Cloud Account.

Dynamic access group assignment from Okta groups

This capability makes it possible to specify an assignment to a specific access group in the IBM Cloud account by using attributes included in the SAML identity claim from Okta. This requires configuration actions in Okta as well as definition of a matching rule in the Access Group on IBM Cloud. The specfics of the definitions, including naming of Okta groups are quite flexible, so this guide will continue along with the scenario of the single Access Group with access to a Cloud Object Storage instance. Before testing the configuration, it is recommended to go in to Manage > Access (IAM) > Users and remove any users that were previously added and manually associated to Access Groups.

Okta application configuration updates

These steps will configure an additional attribute accessgroup to be sent during SAML authentication. These steps are based upon the Update profile with attribute statements documentation which can be consulted for further details.

If one has not been created already, in the Okta Admin Console open Directory > Groups add a group called cos-demo
Assign any desired people (users) to this group.
Go to Directory > Profile Editor
Select the IBM Cloud AppID User item shown in the Profile Editor
Click on Add Atrribute, and keep the data type as string
Set the Display name* to Access Group
Set the Variable name to accessgroup
Provide a Description if desired and set the Attribute type to Group
Click on Save to add the attribute to the application
Go in to the Applications configuration page and select the IBM Cloud AppID application
On the Assignments tab, remove any test users that were associated outside of a group assignment
Click on Assign > Assign to Groups, then select Assign item for cos-demo
The next panel will prompt for a value to give the the Access Group attribute. Enter COS-demo and click on Save and Go Back, then click on Done or add other Okta groups to the application as needed.
Switch to the General tab, scroll down to SAML Settings and click on Edit
Skip to Step 2 Configure SAML and scroll down in the settings to the Attribute Statements section
Add one more attribute with Name = accessgroup, Name Format = Basic, and Value = appuser.accessGroup

If desired, Preview the SAML Assertion - if the current user is in the cos-demo group, then the additional Attribute will be shown:

<saml2:Attribute Name="accessgroup" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
     <saml2:AttributeValue
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">COS-demo
     </saml2:AttributeValue>
</saml2:Attribute>

Click on Next and Finish to complete the update to the Application Integration.

IBM Cloud Access Group dynamic rule configuration

On the IBM Cloud account, a dynamic rule needs to be added to the target Access Group to match the value in the SAML attribute.

In IBM Cloud open Manage > Access(IAM) > Access groups and select the COS-demo access group.
Select the Dynamic rules tab and click on Add
Enter a name like okta and then for Authentication method, select "Users Federated by IBM Cloud App ID"
Select the Identity Provider added in Enabling external authentication using AppID which was Okta
For the rule, enter in accessgroup for Allow users when, set the Qualifier to Contains and specify the Values as COS-demo

in this case, it would also be correct to use Equals instead of Contains
Enter in the desired duration for the dynamic assignment to last. Adjust this to company policy as needed. For testing leave at 1 hour.
Click on Save to apply the rule.

Testing access group assignment from Okta groups

At this point, use either the Default IdP URL or the Okta Dashboard application to initiate a login to the IBM Cloud account. After the login completes, as a user with IAM access to the Access Group, check to confirm that the user is shown with the Type of Dynamic. In this example the test user should still have the same access to the Cloud Object Storage instance as was working from the manual assignment.

To troubleshoot, it is possible to inspect the user's SAML attributes from the App ID instance. Open the control panel for the App ID instance and select Profiles and roles > User Profiles. Select the Identifier link for the user and review the information in the Summary panel. Under the identities list, the entry for the saml provider will list attributes decoded from the identity claim from the IdP. In addition to the username, firstname, and lastname attributes the new accessgroup attribute should be listed with the expected value.

References

This guide draws from the AppID SAML setup documentation and also the IBM Cloud External Authentication documentation.

timroster/okta-appid.md