Recently, while thinking about what topic I should select for a new article, my gaze stopped on my desk. As often, a Batman comic was next to my right screen (for those who wonder, it was “Gotham Nocturne”). Then came to me a very geeky idea : if I were to explain some Okta concepts to a friend, I would use Batman’s lore.
Don’t be afraid, I will not give a lesson about the Dark Knight, I am pretty sure everyone knows a little about him (his identity, his purpose, how he chose to become the Batman…). Instead, I will try to use metaphors and comparisons with its lore to explain what is Okta API Access Management.
Okta in the Batman universe
You can think of the Okta WIC (Workforce Identity Cloud) organization as the Batcave. It is something you can access only if you have been added as a user by an administrator (for the moment, let’s not talk about HR-driven imports or automated provisioning). Some resources will be available to you, others will not. You may have been assigned some applications, and were put in some groups. Moreover, to access the Batcave, some of users will have to use a password, or use a retinal scan. Yes, Batman uses MFA (multi-factor authentication – he’s at the cutting edge of technology).
Therefore, consider Batman as a super administrator. He has rights upon everything, handles the organization’s management. He can grant other users standard admin roles, assign them applications, or even build custom admin roles to assign them very specific rights upon some resources.
As a super admin, Batman would probably grant admin rights to Nightwing, Robin and other sidekicks, but not necessarily the same.
Think of the apps in Okta as Batman vehicles : Robin is not allowed to ride Nightwing’s bike, but can have a passenger seat in the Batmobile. You get the idea?
Before going on with the main topic of the Okta API access management, I will make another metaphor : think of APIs as all data resources Batman owns. His files and folders about all the criminals of Gotham are not at free disposal of everyone. Your APIs are neither unprotected, one must be authenticated and authorized to access your resources.
Oka API Access Management
Okta API Access Management (APIAM) is a paid feature that allows you to build custom authorization servers, which you then use to protect your own API endpoints. Note that APIAM is included in the (free) Okta developer organizations, as the goal is to allow developers to fully discover its utility.
Authorization servers
An authorization server is an engine whose purpose is to deliver Access tokens, which are the representation of a specific access granted for a user or another machine to some specific resources. It uses OAuth 2.0, which is an industry-standard protocol for authorization, and the overlay OpenID Connect (OIDC) to generate an Id token alongside.
Inside the Batman universe, an authorization server is like the Bat-computer.
Regarding who is using it, the Bat-computer will allow or deny access to resources requested. The request can be made by a user, like Robin, who wants to know every known lair of the Riddler for instance. But the request could also come from another Okta organization, like if Oracle (Barbara Gordon, when retired as Batgirl, after she’s been shot by the Joker and left paralyzed) uses her own computer from her watchtower to access data.
In each use case, a request is made to the authorization server, based on the Access token of the user or the machine requesting. The Access token’s scopes, claims, and information about the issuer, its lifetime are what the authorization server verifies before making a decision.
Access Token, scopes and claims
In Okta API, Access tokens are in the form of Json Web Tokens (JWT). Keep in mind they contain claims, which are info about the entity that requested the token (“sub” – for subject), the issuer of the token (“iss”), a timestamp of the moment it was issued (“iat”), its lifetime (“exp”), the expected audience (“aud” – a clientId here), and other custom informations
Let’s have a look at what would look like an Access token issued to Red Hood, one of Batman’s allies :
{
"sub": "1234567890",
"name": "Red Hood",
"iss": "9xg45XDe34",
"aud": "0oa9rt9d91hy1iS8Z1d7",
"iat": 1693487184,
"exp": 1693490784,
"jti": "ID.fVwsJy_qCrcp23etC_1EtK6iKLby2kPdZp-75TYU47hAk",
"amr": [
"pwd"
],
"admin": true,
"role": "ally",
"true_Id": "Jason Todd"
}
In this token, the “true_Id” claim is custom whereas “name” or “amr” are examples of registered (standard) claims.
Scopes
The scopes are the permissions granted to users : they define what users can do or not. Unlike claims which are received in an Access token, scopes are sent with the authorization request. In an Okta tenant, you may have default and custom scopes.
If Red Hood had requested an Access Token with the authorization code flow, it could look like this:
https://batcomputer.com/oauth2/v1/authorize?client_id=0op8xwtmarwTfDzDT427&redirect_uri=https%3A%2F%2Foidcdebugger.com%2Fdebug&scope=openid%20profile%20email%20address&response_type=code&response_mode=form_post&state=4a8wvmqbbea&nonce=96vc3gdc6jdThe default scopes return standard information about the user (like “email”, “address”), except the “openid” scope : this one is use to indicate that the authorization request is made with the OIDC protocol. In that case, an Id token is received with the Access token. The “profile” scope returns your own profile informations.
Okta API scopes versus custom scopes
As for the Okta API scopes, they can only be used with the Org Authorization Server, and in the sole use case of making requests to the Okta API. As it is a pre-defined authorization server that is not intended for modification, the Org Authorization Server cannot be seen on the Okta tenant. These scopes have crystal clear designation that tells what their permission is about. For instance, “okta.users.read” allows to only read user information whereas “okta.users.manage” gives the ability to read and modify the users’ profile information. For more details, you can have a look at the scopes list.
On the other side, Okta APIAM provides you with the ability to build and use custom Authorization servers, and define your own scopes and claims. Unlike the Okta API scopes, there is no pre-existing list of custom scopes : they are yours to define, to answer your needs at best, requesting a custom-built API. If you paid for APIAM, you will have a default custom authorization server, whose name is “default” (no suspense).
Access policies
So, as far as we are, you are now aware that with APIAM, you have a default authorization server and custom authorization servers. You can define custom scopes, and custom claims.
Yet, as you probably have guessed, that is not all that APIAM provides you with. Access Policies is another interesting part: it allows you to determine a custom authorization server’s response on the Access token’s configuration level, for a specific OIDC application. For each access policy, you can set different rules to answer specific needs. To reach this feature, you must follow the menu path “Security” > “API” and then, on your targeted custom authorization server, click on the pen icon.
In each rule, you can set:
- which grant type can be used
- if the rule has to be applied to any user or to user from a specific group
- if a specific scope must be requested
- the use of an inline hook if needed
- the token lifetime
- the refresh token lifetime, including an expiry time if the token has not been used
Pretty useful when you want a custom and specific configuration for one OIDC application, isn’t it ? You must now wonder how you can ensure your rule is valid and will correctly apply like you expect it. The “Token Preview” tab will help you with that.
A simple use case
For this example, I created a custom scope named “userType” which value returns “user.title”, and then a custom claim named “Role”, for which Red Hood’s value will return “ally”. This custom claim is included in my custom scope. I set an access policy that set the Access token lifetime to 8 hours, if my custom scope “userType” is requested.
Here you can see what the token preview shows when we simulate an Access token request by Red Hood with the scope “userType”, for the OIDC application “Bat-computer”.
Everything worked so far, as the request was consistent with the access policy and its rule. If Red Hood had tried the request without the “userType” scope and used “openid” and “profile” instead, it would have failed.
Conclusion
I guess you now see more clearly the whole picture. So, here is a little recap of what you get with Okta APIAM:
- You have a complete and precise control of who can access you APIs, and how they can do it.
- You can define several rules and access policies, each one answering a specific need.
- You can build custom authorization servers, and use them for a specific purpose.
- Access policies let you complete the protection of API routes in code
Therefore, you cover every possible situation. Like Batman, you leave no room for luck, everything is under control.
Remember this feature is included in Okta developer tenants, yet you have to pay for this feature in preview and production Okta organizations.
Now, if you’ll excuse me, I can see something through my window, I have to go.
Point Base is an Okta partner company, our services:
- Consulting
- Training
- Implementation
- Software development
We now also work with Perimeter 81 and Sysdig
Don’t hesitate to follow Point Base’s LinkedIn page.
Do you have any questions? Contact us, we’ll be delighted to answer them.
