Table of Contents¶

Provider¶

The Plan B Provider issues signed JSON Web Tokens (JWT) as response to Access Token Requests with a valid Resource Owner Password Credentials Grant.

An example token creation response (/oauth2/access_token endpoint):

{
    "access_token": "eyJraWQiOiJ0ZXN0a2V5LWVzMjU2IiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0MiIsInNjb3BlIjpbImNuIl0sImlzcyI6IkIiLCJyZWFsbSI6Ii9zZXJ2aWNlcyIsImV4cCI6MTQ1NzMxOTgxNCwiaWF0IjoxNDU3MjkxMDE0fQ.KmDsVB09RAOYwT0Y6E9tdQpg0rAPd8SExYhcZ9tXEO6y9AWX4wBylnmNHVoetWu7MwoexWkaKdpKk09IodMVug",
    "id_token": "eyJraWQiOiJ0ZXN0a2V5LWVzMjU2IiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0MiIsInNjb3BlIjpbImNuIl0sImlzcyI6IkIiLCJyZWFsbSI6Ii9zZXJ2aWNlcyIsImV4cCI6MTQ1NzMxOTgxNCwiaWF0IjoxNDU3MjkxMDE0fQ.KmDsVB09RAOYwT0Y6E9tdQpg0rAPd8SExYhcZ9tXEO6y9AWX4wBylnmNHVoetWu7MwoexWkaKdpKk09IodMVug",
    "token_type": "Bearer",
    "expires_in": 28800,
    "scope": "cn",
    "realm": "/services"
}

The JWT header contains the ID of the signing key and the used algorithm:

{
    "kid": "testkey-es256",
    "alg": "ES256"
}

The JWT payload contains the user ID (sub claim), realm and granted scopes:

{
    "sub": "test2",
    "scope": [
        "cn"
    ],
    "iss": "B",
    "realm": "/services",
    "exp": 1457319814,
    "iat": 1457291014
}

Token Info¶

The Plan B Token Info validates signed JWT tokens using the right public key (exposed by the Provider) and checks the token against any revocation lists.

The /oauth2/tokeninfo validation response contains details about the OAuth2 access token:

{
    "access_token": "eyJraWQiOiJ0ZXN0a2V5LWVzMjU2IiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0MiIsInNjb3BlIjpbImNuIl0sImlzcyI6IkIiLCJyZWFsbSI6Ii9zZXJ2aWNlcyIsImV4cCI6MTQ1NzMxOTgxNCwiaWF0IjoxNDU3MjkxMDE0fQ.KmDsVB09RAOYwT0Y6E9tdQpg0rAPd8SExYhcZ9tXEO6y9AWX4wBylnmNHVoetWu7MwoexWkaKdpKk09IodMVug",
    "cn": true,
    "expires_in": 28292,
    "grant_type": "password",
    "open_id": "eyJraWQiOiJ0ZXN0a2V5LWVzMjU2IiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0MiIsInNjb3BlIjpbImNuIl0sImlzcyI6IkIiLCJyZWFsbSI6Ii9zZXJ2aWNlcyIsImV4cCI6MTQ1NzMxOTgxNCwiaWF0IjoxNDU3MjkxMDE0fQ.KmDsVB09RAOYwT0Y6E9tdQpg0rAPd8SExYhcZ9tXEO6y9AWX4wBylnmNHVoetWu7MwoexWkaKdpKk09IodMVug",
    "realm": "/services",
    "scope": ["cn"],
    "token_type": "Bearer",
    "uid": "test2"
}

Revocation Service¶

The Plan B Revocation Service manages token revocation lists and provides them to Token Info.

See the Revocations section for details.

Authorization Grant¶

The Plan B Provider currently supports the following grant types:

Authorization Code Grant Type

Client redirects to Plan B and user logs in with his credentials. This grant type is used for User to Service authentication.

Implicit Grant Type

In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly via browser redirect. Plan B allows the implicit flow only for clients which are flagged as “non-confidential”.

Resource Owner Password Credentials Grant Type

User and client credentials are directly exchanged for an JWT access token. This grant type is mostly used for Service to Service authentication where user and client OAuth credentials are known to the service by some form of “secret distribution”.

Access Token¶

The Plan B Provider issues access tokens in the JWT format which can be used as Bearer Tokens and validated against the Plan B Token Info.

The issued JWT tokens have the following properties:

• The access token is valid for 8 hours.
• The JWT is signed with a JSON Web Signature (JWS) and therefore has a corresponding JOSE Header and JWS signature
• The JOSE header always contains the signing key ID (kid) and signing algorithm (alg)
• The JWT payload always contains the following claims:
  • subject (sub)
  • realm (realm)
  • scopes (scope)
  • issuer (iss)
  • expiration date (exp)
  • issue date (iat)
• The JWT payload will additionally contain the OAuth client ID in the azp claim if the “azp” scope was requested (and granted)

An example JWT access token issued by Plan B Provider might look like (line breaks were added for readability):

eyJraWQiOiJ0ZXN0a2V5LWVzMjU2IiwiYWxnIjoiRVMyNTYifQ.
eyJzdWIiOiJ0ZXN0MiIsInNjb3BlIjpbImNuIl0sImlzcyI6IkIiLCJyZWFsbSI6Ii9zZXJ2aWNlcyIsImV4cCI6MTQ1NzMxOTgxNCwiaWF0IjoxNDU3MjkxMDE0fQ.
KmDsVB09RAOYwT0Y6E9tdQpg0rAPd8SExYhcZ9tXEO6y9AWX4wBylnmNHVoetWu7MwoexWkaKdpKk09IodMVug

The JOSE header contains:

{
    "kid": "testkey-es256",
    "alg": "ES256"
}

The JWT payload contains:

{
    "sub": "test2",
    "scope": [
        "cn"
    ],
    "iss": "B",
    "realm": "/services",
    "exp": 1457319814,
    "iat": 1457291014
}

Refresh Token¶

The Plan B Provider does not support refresh tokens.

Protocol Endpoints¶

Authorization Endpoint¶

The Plan B Provider Authorization Endpoint does not yet support the optional OpenID Connect request parameters.

Token Endpoint¶

The Plan B Provider Token Endpoint returns an ID token (id_token).

OpenID Provider Configuration Information Endpoint¶

The Plan B Provider supports the OpenID Connect Discovery endpoint /.well-known/openid-configuration.

Only the jwks_uri has a meaningful value in the OpenID Provider Configuration Response.

Service Users¶

To rotate an application’s user credentials, do:

• Add a new password by sending a POST request to /raw-sync/users/{realm}/{id}/password.
• Distribute the new password (e.g. via a S3 Mint Bucket).
• Wait at least 10 minutes to give the application time to pick up the new password. Both old and new password will be active during this grace period.
• Commit the new password by overwriting the user’s passwords via a PATCH request to /raw-sync/users/{realm}/{id}.

Clients¶

OAuth client credentials can be rotated by creating a new client and deactivating or deleting the old one:

• Create a new client by sending a PUT request to /raw-sync/clients/{realm}/{id} (see below).
• Distribute the new client credentials (e.g. via a S3 Mint Bucket).
• Wait at least 10 minutes to give the application time to pick up the new client credentials. Both old and new client will be active during this grace period.
• Reset the old client’s secret to some random string or delete the old client completely.

Example REST call to create a new client in the /services realm using HTTPie:

$ SECRET_HASH=$(python3 -c "import bcrypt; print(bcrypt.hashpw(b'test', bcrypt.gensalt(4)).decode('ascii'))")
$ TOK='mytoken' # valid OAuth token
$ http PUT https://planb-provider.example.org/raw-sync/clients/services/myclient-123 \
  is_confidential:=true \
  name='Example Client'\
  secret_hash=$SECRET_HASH \
  "Authorization:Bearer $TOK"

Revoking a Single Token¶

$ tok=... # some valid token accepted by the configured TOKENINFO_URL
$ curl -X POST \
     -H "Authorization: Bearer $tok" \
     -H 'Content-Type: application/json' \
     -d '{"type": "TOKEN", "data": {"token": "..."}}' \
     "https://planb-revocation.example.org/revocations"

Revoking Tokens by Claims¶

Revoking all tokens issued up to now with subject (username) “jdoe”:

$ tok=... # some valid token accepted by the configured TOKENINFO_URL
$ curl -X POST \
     -H "Authorization: Bearer $tok" \
     -H 'Content-Type: application/json' \
     -d '{"type": "CLAIM", "data": {"claims": {"sub": "jdoe"}}}' \
     "https://planb-revocation.example.org/revocations"

Forcing Token Info to refresh from certain Timestamp¶

$ tok=... # some valid token accepted by the configured TOKENINFO_URL
$ curl -X POST \
    -H "Authorization: Bearer $tok" \
    https://planb-revocation.example.org/notifications/REFRESH_FROM?value=123

Cassandra¶

The Cassandra cluster should be closely monitored using the usual Cassandra JMX beans, e.g.:

• Number of UP/DOWN nodes
• Number of Read/Write requests per second
• Read/Write latency

Provider¶

The Provider exposes metrics on its management port 7979 with path /metrics.

planb.provider.access_token.{realm}.success

DropWizard timer for successful access token requests by realm.

planb.provider.access_token.{realm}.error.{errortype}

DropWizard timer for failed access token requests by realm and error type.

The Provider is mostly CPU-bound by its BCrypt password checking and JWT signing operations. Monitoring the CPU usage percentage is therefore strongly recommended.

Token Info¶

The Token Info exposes metrics on its metrics port 9020 with path /metrics.

planb.openidprovider.numkeys

Number of public keys in memory.

planb.tokeninfo.jwt.{realm}.requests

Timer for the JWT handler (one timer per realm).

planb.tokeninfo.proxy

Timer for the proxy handler (includes cached results and upstream calls).

planb.tokeninfo.proxy.cache.hits

Number of upstream cache hits.

planb.tokeninfo.proxy.cache.misses

Number of upstream cache misses.

planb.tokeninfo.proxy.cache.expirations

Number of upstream cache misses because of expiration.

planb.tokeninfo.proxy.upstream

Timer for calls to the upstream tokeninfo. Cached responses are not measured here.

The Token Info is mostly CPU-bound by its JWT signature verification operations. Monitoring the CPU usage percentage is therefore strongly recommended.

STUPS¶

Plan B can be seamlessly integrated into the STUPS infrastructure:

• The mint worker can automatically create and rotate application OAuth users for all applications registered in Kio
• The mint worker can distribute OAuth credentials via S3 buckets

Libraries¶

The following libraries are compatible with Plan B: