OpenID Connect API reference

You are browsing unreleased documentation.

Using the OpenID Connect API

The OpenID Connect plugin extends the Kong Admin API with endpoints for configuring discovery caches and JWKs.

To configure and enable the plugin itself, use the /plugins API endpoint. The /openid-connect endpoints only appear once the plugin has been enabled.

Discovery Cache

When configuring the plugin using config.issuer, the plugin will store the fetched discovery information to the Kong database, or in the worker memory with DB-less. The discovery cache does not have an expiry or TTL, and so must be cleared manually using the DELETE endpoints listed below.

The discovery cache will attempt to be refreshed when a token is presented with required discovery information that is not already available, based on the config.issuer value. Once a rediscovery attempt has been made, a new attempt will not occur until the number of seconds defined in rediscovery_lifetime has elapsed - this avoids excessive discovery requests to the identity provider.

If a JWT cannot be validated due to missing discovery information and an invalid status code is received from the rediscovery request (for example, non-2xx), the plugin will attempt to validate the JWT by falling back to any sufficient discovery information that is still in the discovery cache.

Discovery Cache Object

{
    "id": "<uuid>",
    "issuer": "<config.issuer>"
    "created_at": <timestamp>,
    "configuration": {
        <discovery>
    },
    "keys": [
        <keys>
    ]
}

List All Discovery Cache Objects

Response

HTTP 200 OK

{
    "data": [{
        "id": "<uuid>",
        "issuer": "<config.issuer>"
        "created_at": <timestamp>,
        "configuration": {
            <discovery>
        },
        "keys": [
            <keys>
        ]
    }],
    "next": null
}

Retrieve Discovery Cache Object

Response

HTTP 200 OK

{
    "id": "<uuid>",
    "issuer": "<config.issuer>"
    "created_at": <timestamp>,
    "configuration": {
        <discovery>
    },
    "keys": [
        <keys>
    ]
}

Delete All Discovery Cache Objects

Response

HTTP 204 No Content

Note: The automatically generated session secret (that can be overridden with the config.session_secret) is stored with the discovery cache objects. Deleting discovery cache objects will invalidate all the sessions created with the associated secret.

Delete Discovery Cache Object

Response

HTTP 204 No Content

JSON Web Key Set

When the OpenID Connect client (the plugin) is set to communicate with the identity provider endpoints using private_key_jwt, the plugin needs to use public key cryptography. Thus, the plugin needs to generate the needed keys. Identity provider on the other hand has to verify that the assertions used for the client authentication.

The plugin will automatically generate the key pairs for the different algorithms. It will also publish the public keys with the admin api where the identity provider could fetch them.

{
    "keys": [{
        <keys>
    }]
}

Retrieve JWKS

This endpoint will return a standard JWK Set document with the private keys stripped out.

Response

HTTP 200 OK

{
    "keys": [{
        <keys>
    }]
}

Rotate JWKS

Deleting JWKS will also cause auto-generation of a new JWK set, so DELETE will actually cause a key rotation.

Response

HTTP 204 No Content