apisix/doc/plugins/openid-connect.md

Summary

• Name
• Attributes
• Token Introspection

Name

The OAuth 2 / Open ID Connect(OIDC) plugin provides authentication and introspection capability to APISIX.

Attributes

Name	Requirement	Description
client_id	required	OAuth client ID
client_secret	required	OAuth client secret
discovery	required	URL of the discovery endpoint of the identity server
realm	optional	Realm used for the authentication; default is apisix
bearer_only	optional	Setting this true will check for the authorization header in the request with a bearer token; default is false
logout_path	optional	default is /logout
redirect_uri	optional	default is ngx.var.request_uri
timeout	optional	default is 3 seconds
ssl_verify	optional	default is false
introspection_endpoint	optional	URL of the token verification endpoint of the identity server
introspection_endpoint_auth_method	optional	Authentication method name for token introspection
public_key	optional	The public key to verify the token
token_signing_alg_values_expected	optional	Algorithm used to sign the token

Token Introspection

Token introspection helps to validate a request by verifying the token against an Oauth 2 authorization server. As prerequisite, you should create a trusted client in the identity server and generate a valid token(JWT) for introspection. The following image shows an example(successful) flow of the token introspection via the gateway.

The following is the curl command to enable the plugin to an external service. This route will protect https://httpbin.org/get(echo service) by introspecting the token provided in the header of the request.

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
  "uri": "/get",
  "plugins": {
    "proxy-rewrite": {
      "scheme": "https"
    },
    "openid-connect": {
      "client_id": "api_six_client_id",
      "client_secret": "client_secret_code",
      "discovery": "full_URL_of_the_discovery_endpoint",
      "introspection_endpoint": "full_URL_of_introspection_endpoint",
      "bearer_only": true,
      "realm": "master",
      "introspection_endpoint_auth_method": "client_secret_basic"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:443": 1
    }
  }
}'

The following command can be used to access the new route.

curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H "Authorization: Bearer {replace_jwt_token}"

Introspecting with public key

You can also provide the public key of the JWT token to verify the token. In case if you have provided a public key and a token introspection endpoint, the public key workflow will be executed instead of verifying with the identity server. This method can be used if you want to reduce additional network calls and to speedup the process.

The following configurations shows how to add a public key introspection to a route.

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
  "uri": "/get",
  "plugins": {
    "proxy-rewrite": {
      "scheme": "https"
    },
    "openid-connect": {
      "client_id": "api_six_client_id",
      "client_secret": "client_secret_code",
      "discovery": "full_URL_of_the_discovery_endpoint",
      "bearer_only": true,
      "realm": "master",
      "token_signing_alg_values_expected": "RS256",
      "public_key" : "-----BEGIN CERTIFICATE-----
        {public_key}
        -----END CERTIFICATE-----"
}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:443": 1
    }
  }
}'

Troubleshooting

Check/modify the DNS settings (`conf/config.yaml) if APISIX cannot resolve/connect to the identity provider.