You get back an administrative access token that doesn’t work

As we all know, you need to use a configuration access token in order to access the OpenID Connect Configuration APIs. Need to create a new OIDC login client or update a token policy? That’s fine; just make sure that: 1) you get an access token; and, 2) you use that access token within the next 60 minutes. (Access tokens expire after one hour.)

That doesn’t seem especially complicated, and most of the time it isn’t. However, it is possible for you to get an access token, try to use that access token right away (i.e., before it expires), and yet your API call still fails with the following error:

What’s the deal here?

Most likely the problem is due to the scope associated with your access token. When you request an access token, you also request a “scope” for that token; the scope dictates what you can and cannot do with that token. For example, this scope (.:**) gives you read-only access to the OpenID Connect Configuration APIs:

If your access token was issued with this scope, that explains why you can’t create a new login policy: your access token limits you to read-only activities. To create, delete, or modify something, you’ll need to get a different access token, one with a different scope.

It’s also possible to get an access token that has no scope, or at least no valid scope. When you go to get an access token, you can request any scope you want; for example, here we’re requesting the non-existent XXXXX scope:

This API call will work, and you will get back an access token. But if you look closely at the API response, you’ll notice that there is no scope associated with the access token:

If your token doesn’t have a scope defining what that token can do, then that token can’t do anything.

And yes, this is a valid token, even though it’s effectively useless. We know that it’s a valid token because it shows up as active when we “introspect” the token:

In other words, you can request any kind of scope (or scopes) that you want. However, the server doesn’t have to honor your request. In fact, the server is limited to handing out scopes specifically included in the token policy used when making the token request. If you look at the allowedScopes property of a token policy you’ll see something similar to this:

"allowedScopes": [
     "openid",
     "*:**",
     "*:config/tokenPolicies",
     "-:config/tokenPolicies/8cdb3f99-ceee-403d-a01d-daf392e1835"
 ]

As you can see, this token policy allows only four scopes:

• openid
• *.**
• *:config/tokenPolicies
• -:config/tokenPolicies/8cdb3f99-ceee-403d-a01d-daf392e1835

And that’s it. If you request any other scope that request will be ignored.

The moral of this story? If your access token isn’t working (and if you know it’s a valid token) check to see which scopes (if any) are attached to the token. Depending on the attached scopes you might have to request a new token and a new scope, and/or add an additional scope or two to your token policy.