This blog post provides step-by-step information on setting up external client management in Mulesoft Anypoint platform. Okta is chosen as external client management to create dynamic client applications and grant, authorize and introspects tokens using Okta. The role of Okta includes creation of Client Id and Client Secret, as well support for OAuth flows – Authorization code and client credential.
This post focuses on below steps
- Create Authorization Server in Okta
- Create Scope in Okta
- Create Token in Okta
- Create Application in Okta
- Register external client management in Anypoint Access Management
- Create Client Application in Anypoint Exchange
- Apply OpenId Connect access token enforcement policy on API
- Test secured API using Postman client.
- Troubleshooting / Debugging
- Mulesoft Anypoint platform account
- Okta developer account
- API deployed on Mulesoft API Manager
- REST Client
1. Create Authorization Server in OKTA
The very first step is to create Authorization Server in Okta, a list of API’s are generated after creation of Authorization Server for issuing, granting, authorizing and introspecting tokens.
Verify details of newly created Authorization server. An Issuer URI is generated.
You can retrieve metadata such as token issuer, introspection and registration by click on field Metadata URI. The metadata has list of supported API’s to fetch required details to setup External Client in Anypoint access management.
Review metadata in browser by hitting provided URI.
2. Create Scope for Authorization Server
Scopes specify access privileges are being requested as part of the authorization. For instance, phone number scope requests access to the user’s phone number.
Select Active Authorization server.
Add new Scope and check option “Include in public metadata”. This option will enable to see details of scope in Metadata.
The scopes are associated with Authorization Server and validate newly created scope in “scopes” of Authorization server.
3. Create Tokens in OKTA
API tokens are used to authenticate requests to the Okta API. API tokens are secrets and should be treated like passwords.
Create and validate tokens on by following below images.
The token value is invisible in Okta UI. At this moment save the token in clipboard or notepad, this is required in later stage to configure in Anypoint platform.
Validate the newly created token API->Tokens
4. Create Application in Okta developer portal
Configuring external client identity in Anypoint platform requires one-time client-id and client-secret to connect to Okta. After one-time configuration of client credentials, the dynamic registration of client applications can be done using Anypoint Exchange request access mechanism. The process of creating new application is one-time, subsequent application creation is done in Mule Anypoint platform. The client application creation in Anypoint platform is described in later part of the post.
Application settings – fill in required details. At this moment, the host “localhost” in fields has no relevance, leave it as it is.
The important flows in OAuth authentication mechanism are Client credentials and Authorization code, choose both the options. In short, both flows generate access tokens and exchanged with Anypoint platform for validation or introspection of token.
The Client credentials flow requires only client_id and client_secret to generate tokens where as authorization flow is complex that requires additional Okta user login credentials. In case of authorization flow the client is prompted with login page, client credentials is a machine to machine interaction.
The details of flows is not described in the post, refer Okta developer portals for additional reference.
5. Register external client management in Anypoint Access Management
Prerequisites to configure external client management in Anypoint platform.
- Access to Anypoint Platform
- Token Value – refer step 3
- Client Id and Client Secret – refer step 4
- Okta API’s – API’s generated in step 1
Login to Anypoint platform -> Access Management -> External Identity-> Client Management -> OpenId Connect Dynamic Client Registration.
Fetch required details such as Issuer, Registration URL, Authorization URL, Token introspection URL, Token URL from Authorization Server metadata and configure in Anypoint platform.
The value of Authorization Header field is token value prefixed by SSWS. The token value in okta is generated in step 3.
6. Create Client Application in Anypoint Exchange.
Check Authorization Code grant option and OAuth redirect URI required for Authorization flow. This value is optional for client credentials.
Validate Client Creation in Okta developer console. The client applications created in Anypoint exchange should be visible in Okta developer console.
Verify credentials and contract in Anypoint platform.
Navigate to Anypoint Exchange -> My Applications.
The Client OktaClientApp1 is associated to API as seen in below image.
Client ID and Client Secret generated for Application OktaClientApp1. The Client ID and Client Secret is used by API Consumer to generate access tokens.
7. Apply policy on API
Navigate to Anypoint platform -> API Manager -> Select API -> Apply New Policy
Apply policy “OpenId Connect access token enforcement” to the selected API.
8. Test API using Postman client
Testing is two step process first accessing token and then exchanging token with API. This post demonstrates testing of OAuth Client Credentials Flow.
Step 1: Use below token end point to access token. Basically, this step is executed by API Consumer.
Token end point – https://dev-893760.okta.com/oauth2/default/v1/token
Required query parameters – client_credentials as grant_type and mulescope as scope.
Required headers – Client ID and Client Secret as Authorization and form-url-encoded as content-type.
Step2 : Test API by passing access token as Basic Authorization.
9. Troubleshooting issues
- Proof Key for code exchange (PKCE) error while accessing token.
error_description: “Browser requests to the token endpoint must use Proof Key for Code Exchange.”
Resolution as per Okta support portal – The “Origin” header is used for client side requests and Okta supports only Authorization flow PKCE as client side OIDC flow on /token endpoint of the authorization server. Any other OpenID Connect flows must send the request through a server side/native method and must not have “Origin” header present.
Was unable to resolve the issue with Postman client as postman sends origin header for every request to access token.
Instead use another REST Clients to access tokens, issue resolved using online REST client https://reqbin.com/
2. Invalid Client Id / Invalid value for ‘client_id’ parameter
This issue encountered while testing Mule API by passing valid access token.
This issue occurs while editing External Identity in Anypoint Access Management and the value of Authorization Header is left blank.
Resolution : The value of Authorization Header field should be “SSWS Token Value”.
3. Introspecting access token
Validate or introspect the token using below end-point.
https://dev-893760.okta.com/oauth2/default/v1/introspect Pass client_id, client_secret and access_token as query parameters.
4. Analyzing Okta Systems logs.
The developer can be clueless on certain errors while accessing token and validating token. Okta developer console provides with system logs to trace and debug in detail.
Login to Okta developer console -> API -> System Log.
The system logs has events of actions taken by API Consumer and API with respect to Okta APIs.
Required to analyse logs in details to know exact root of cause of issues.
Thank you for reading this article, do let us know your view by dropping us a comment.
Also, if you are interested in learning more about an exciting new code review and code quality product that reduces your Mule project costs by 79%, follow the below link :