Developing an authentication flow for your service
When you onboard your product to IBM Cloud® Partner Center, you can develop an authentication flow to securely identify and verify users as they access your services. Developing an authentication flow allows you to protect your product and ensures that your service integrates securely within IBM Cloud.
Before you begin
Before you can start developing an authentication flow, you must have a client ID and a secret configured.
Configuring your client ID and secret
To develop an authentication flow, you need a client ID and a secret, and a redirect URL. The client ID is generated to identify your service, along with the secret, which is the password for your service. Your client ID is not confidential since it is publicly identified. However, the secret is confidential and is only known to the application and the authorization server. You can create and manage you client ID in Partner Center. A redirect URL is the host URL for your service that users are redirected to after a successful authentication.
The following example shows redirect URLs:
https://<myapp>.cloud.ibm.com/integrate/auth/callback
http://localhost:3000/auth/callback <-- for testing locally
To generate your client ID, complete the following steps:
-
In the IBM Cloud console, click the Navigation Menu icon
> Partner Center > My products.
-
Select the product that you're onboarding, and go to the Brokers page.
-
Click Set up IBM Cloud SSO.
-
Add owners who can manage the client ID.
Only owners are able to view, edit and delete the client ID setup, or add extra redirect URLs. Users who create the client ID are automatically added to the owners list, and not able to remove themselves.
-
Add the redirect URL, and click Next. You can add more than one URL and use these as the
redirect_uri
in the upcoming tasks. Theredirect_uri
value refers to the redirect URL. -
Save your credentials. Copy the password for your service that is generated along with the client ID. You are not able to retrieve your password later.
If you don't have your password, you can delete and re-create your previously created client ID to generate another one.
-
Click Done.
Step 1: Finding the regional endpoint
After you successfully generate your client ID, you can start developing the oAuth flow. First, find the IAM regional endpoint for UI login that is closer to your deployed application by calling the following endpoint:
https://iam.cloud.ibm.com/identity/.well-known/openid-configuration
See the following curl command as an example:
curl -X GET \
https://iam.cloud.ibm.com/identity/.well-known/openid-configuration
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer": "https://iam.cloud.ibm.com/identity",
"authorization_endpoint": "https://iam-region2.cloud.ibm.com/identity/authorize",
"token_endpoint": "https://iam-region2.cloud.ibm.com/identity/token",
...
}
This request can be done when the application starts, and again if the authorization_endpoint
fails. You can cache the authorization_endpoint
value for a short amount of time, and refresh after the cache expires or
an error occurs.
Step 2: Redirecting users to your dashboard_url
When users navigate to your dashboard_url
, redirect the browser to the following URL to check whether they are logged in to your application and have the access token:
<authorization_endpoint>?client_id=<your-client-id>&redirect_uri=<your-redirect-uri>&response-type=code&state=<your-resource-instance-id>
The redirect_uri
value refers to the redirect URL that you set up in the Configuring your client ID and secret step.
-
If a user is logged in, they are immediately redirected. The browser does a callback to redirect the URI with a
code
response parameter andstate
value. -
If a user is not logged in, a login prompt appears. After a successful login, the browser does a callback to redirect the URI with a
code
response parameter andstate
value.
Step 3: Calling the access token endpoint
After the user successfully logged in, exchange the code that you received in Step 2 for the access token of the user by calling the access token endpoint.
POST request to the token endpoint
To obtain an access token, you must include the following headers and parameters:
Headers
Authorization: Basic [client id]:[client secret]
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Parameters
Mandatory
grant_type=authorization_code
response_type=cloud_iam
redirect_uri=[this parameter refers to the same URL from Step 1]
code=[code from callback]
Optional
account=<account ID for the token>
It is highly recommended to obtain an account-scoped token.ip_address=<IP address of the user>
Pass the IP address of the user if it differs from the client IP.
See the required headers and parameters included in the following POST request example:
curl -k -X POST \
-u "<your-client-id>:<your-client-secret>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "response_type=cloud_iam" \
--data-urlencode "account=<account ID for the token>" \
--data-urlencode "ip_address=<IP address of the user>" \
--data-urlencode "code=<code-from-the-callback>" \
--data-urlencode "redirect_uri=<redirect_uri>" \
"https://iam-region2.cloud.ibm.com/identity/token"
Access token response
After you submit a POST request in the previous task, you receive a response with the access token.
See the following example of a successful access token response:
{
"access_token": "eyJraWQiOiI......XmpBTIDdR5w",
"refresh_token": "SPrXw5tBE3......KBQ+luWQVY=",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1473188353
}
IAM token scoping for third-party service providers
User access tokens that are created with your client ID can be used to access only your service APIs. Requests to other IBM Cloud APIs that use this token are denied access, even if the user has an appropriate policy configured.
As part of third-party integration, token scoping is being used to ensure that tokens have the minimal access scope that is needed to accomplish the user's goals. To facilitate this, IAM tokens access is based on the client ID that created the token.