Name

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

Attributes

NameRequirementDescription
client_idrequiredOAuth client ID
client_secretrequiredOAuth client secret
discoveryrequiredURL of the discovery endpoint of the identity server
realmoptionalRealm used for the authentication; default is apisix
bearer_onlyoptionalSetting this true will check for the authorization header in the request with a bearer token; default is false
logout_pathoptionaldefault is /logout
redirect_urioptionaldefault is ngx.var.request_uri
timeoutoptionaldefault is 3 seconds
ssl_verifyoptionaldefault is false
introspection_endpointoptionalURL of the token verification endpoint of the identity server
introspection_endpoint_auth_methodoptionalAuthentication method name for token introspection
public_keyoptionalThe public key to verify the token
token_signing_alg_values_expectedoptionalAlgorithm 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.

token introspection

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.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.   "uri": "/get",
  4.   "plugins": {
  5.     "proxy-rewrite": {
  6.       "scheme": "https"
  7.     },
  8.     "openid-connect": {
  9.       "client_id": "api_six_client_id",
  10.       "client_secret": "client_secret_code",
  11.       "discovery": "full_URL_of_the_discovery_endpoint",
  12.       "introspection_endpoint": "full_URL_of_introspection_endpoint",
  13.       "bearer_only": true,
  14.       "realm": "master",
  15.       "introspection_endpoint_auth_method": "client_secret_basic"
  16.     }
  17.   },
  18.   "upstream": {
  19.     "type": "roundrobin",
  20.     "nodes": {
  21.       "httpbin.org:443": 1
  22.     }
  23.   }
  24. }'

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

  1. 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.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.   "uri": "/get",
  4.   "plugins": {
  5.     "proxy-rewrite": {
  6.       "scheme": "https"
  7.     },
  8.     "openid-connect": {
  9.       "client_id": "api_six_client_id",
  10.       "client_secret": "client_secret_code",
  11.       "discovery": "full_URL_of_the_discovery_endpoint",
  12.       "bearer_only": true,
  13.       "realm": "master",
  14.       "token_signing_alg_values_expected": "RS256",
  15.       "public_key" : "-----BEGIN CERTIFICATE-----
  16.         {public_key}
  17.         -----END CERTIFICATE-----"
  18. }
  19.   },
  20.   "upstream": {
  21.     "type": "roundrobin",
  22.     "nodes": {
  23.       "httpbin.org:443": 1
  24.     }
  25.   }
  26. }'

Troubleshooting

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