Validating Foreign Access Tokens
Aidbox can validate access tokens issued by 3rd-party servers. This way Aidbox acts as a Resource Server and leaves Identity management to a separate server.
To configure Aidbox as a Resource Server, you need to create one or more instances of TokenIntrospector resource. TokenIntrospector resources defines how access token validation will be performed. There are two different algorithms to validate tokens: JWT validation according to RFC-7519 and opaque token introspection according to RFC-7662.

Validating JWT Access Tokens

For JWT validation, you need to specify either JWKs endpoint URL (RFC-7517) or a pre-shared secret string if tokens are signed with HS256 algorithm:
1
resourceType: TokenIntrospector
2
type: jwt
3
jwks_uri: https://.../.well-known/jwks.json
4
jwt:
5
iss: https://my-provider.example # shoud be equal to `iss` claim of the JWT
6
secret: "xxxxxxxx" # pre-shared key if JWT alg = HS256
Copied!
When Aidbox validates the JWT token, it tries to find a matching TokenIntrospector using jwt.iss and type attributes. If suitable TokenIntrospector is found, token is being validated with either JWK obtained from jwks_uri or with jwt.secret, depending on the signing algorithm. Token expiration (exp claim) is also being checked.
If JWT is valid, Aidbox will put it's claims into the request object under jwt key, so you'll be able to access them with AccessPolicy checks. If the token failed validation (it's expired or signature isn't correct) then the client will get a 401 "Unauthorised" response.

Validating Opaque (non-JWT) Tokens

When using old-fashioned (opaque) tokens, Aidbox can be configured to call a special endpoint with every new access token it receives. This endpoint, called a token introspection endpoint, returns information about access token - scopes, username and client ID associated with it, expiration time, etc. Most importantly, it tells if access token is active or not.
To configure Aidbox in this way, create TokenIntrospector instance with opaque type and introspection_endpoint attribute:
1
resourceType: TokenIntrospector
2
type: opaque
3
introspection_endpoint:
4
url: https://.../oauth/token_introspection # endpoint URL
5
authorization: Bearer xxxyyyzzz # value for Authorization header
Copied!
According to RFC-7662, the only required attribute in token introspection's response is active. Aidbox uses this attribute to consider if token is valid or not. If token is valid, entire token introspection's response will be put into the request's object under token key, so you'll be able to use it in AccessPolicy checks. If token isn't valid, Aidbox will try to validate access token against currently active local sessions.

X-Client-Auth

In some situations (like micro-services), you want to add middle-ware client authentication. You can use the X-Client-Auth header with basic auth value for client id and secret to add client authentication to the JWT workflow.
1
GET /Patient?_debug=query
2
Authorization: Bearer <your-jwt>
3
X-Client-Auth: Basic <basicEncode(Client.id, Client,secret)>
4
5
# 200
6
7
request:
8
client: .....
9
jwt: ....
10
Copied!

Examples

Access control with Validating JWT Access Tokens and AccessPolicy
Create TokenInspector
1
resourceType: TokenIntrospector
2
type: jwt
3
jwks_uri: https://.../.well-known/jwks.json
4
jwt:
5
iss: https://my-provider.example # shoud be equal to `iss` claim of the JWT
6
secret: "xxxxxxxx" # pre-shared key if JWT alg = HS256
Copied!
Your JWT token should contain sub attribute that equal User.id on your box.
1
# JWT sample
2
...
3
claims:
4
...
5
sub: box-user-id
6
Copied!
Also you can put box user id in to box_user claim attribute. This makes sense when you use external oauth provider or any other identity system that manages sub attribute itself. In this case, you can put the box user id in to box_user .
1
# JWT sample
2
...
3
claims:
4
...
5
sub: some-user-id-on-external-system
6
box_user: box-user-id
7
Copied!
When Aidbox receives request with JWT and box_user or sub attribute, Aidbox injects this user and their roles to the request. Now we can create some AccessPolicy.
1
# AccessPolicy example
2
resourceType: AccessPolicy
3
engine: allow
4
link:
5
- resourceType: User
6
id: box-user-id
Copied!
Last modified 8mo ago