Client authentication support: private_key_jwt

Client authentication support: private_key_jwt

Identify OAuth 2.0 service provider allows its users to authenticate their clients with a private_key_jwt method.

When an authorization server authenticates its clients with the private_key_jwt method, the clients must send a request that contains an assertion in JWT format, to the token endpoint of the server. And the authorization server must validate the signature and payload of the assertion, which is described as follows.

Discovery endpoint

The discovery endpoint returns a list of supported client authentication methods which indicate that private_key_jwt is supported:

Dynamic client registration endpoint

Please visit the Client metadata section for more details about supported keys:

Key name
token_endpoint_auth_method
jwks
jwks_uri

Protocol

Setting up OAuth2.0 protocol connection for private_key_jwt

You need to update the settings below:

  • Token endpoint authentication method: Set to PrivateKeyJwt
  • Register the client's public key jwks to the setting Client's registered jkws which are used for verifying client_assertion or its jwks_uri to the setting: A client's uri from which Safewhere Identify can fetch its jkws that are used for verifying client_assertion. Please note that these 2 settings cannot be set at the same time. Only one of them can be used. Otherwise, the connection cannot be saved.

For the Identify Admin, you can find the options in the OAuth2.0 protocol connection:

identify-admin-private-key-jwt

For the Safewhere Admin, you can find the option in the OpenID Connect/OAuth2.0 application's connection settings:

sw-admin-private-key-jwt

For the REST API, you can add the properties named "clientJwks"/ "clientJwksUri" / "tokenEndpointAuthenticationMethod" into its "configuration" connection JSON element.

Client application

The client must send a request that contains the following parameters to the token endpoint when using the private_key_jwt method.

Parameter Description
client_assertion_type The value must be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion A JWT that contains information for client authentication

The value of the client_assertion must be a signed JWT that contains information for the client authentication and meet the following requirements:

  • Signing: The JWT must be signed using an SHA-256 algorithm.
  • The JWT must contain the REQUIRED claims listed below:
    • iss: REQUIRED. The Issuer claim that MUST contain the client_id of the OAuth Client.
    • sub: REQUIRED. The Subject claim that MUST contain the client_id of the OAuth Client.
    • aud: REQUIRED. The Audience claim that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.
    • jti: REQUIRED. A unique identifier (JWT ID) for the token, which can be used to prevent reuse of the token. These tokens MUST only be used once, unless conditions for reuse were negotiated between the parties; any such negotiation is beyond the scope of this specification.
    • exp: REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
    • iat: OPTIONAL. Time at which the JWT was issued.

Request URL:

Request body example:

Name Value
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion eyJhbGciOiJSUzI1NiIsImtpZCI6IjVFVVA5dEZqYkJtYUJEY2Y1Q1FhaXBOSFVHZyIsIng1dCI6IjVFVVA5dEZqYkJtYUJEY2Y1Q1FhaXBOSFVHZyIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3ZWJtdmNfY29kZWZsb3dfaWQiLCJhdWQiOiJodHRwczovL2lkZW50aWZ5ZGV2NTYuc2FmZXdoZXJlLmxvY2FsL3J1bnRpbWUvb2F1dGgyL3Rva2VuLmlkcCIsImV4cCI6MTg5NjU3OTU1OCwianRpIjoiY2RmYzIzNTgtOWVhOS00NWMyLWEzMjQtNzU0Yzk5NWUzYTUxIiwibmJmIjoxNTgwOTYwMzU5LCJpYXQiOjE1ODA5NjAzNTgsImlzcyI6IndlYm12Y19jb2RlZmxvd19pZCJ9.fuMtptdUlrcXcPxW4jngaggO7pgz2DxoUDpXYAEls0JHsKuxDmSTlcmhV1LaXOMqeIbUlt6d1LioXvGMwviCO3Nyeggqq6_yVlw0sr16WOCsXe28zky5iJvTwywobKjicLtclaLhNmuW9MMDr9MxaMwy_lpXWt-jfV_uE6EbrJ3DpowbXezkXRgWUQjfL8Efp68m65FN8cJmFncrit6vi28O3r8_Bybxz4JxnSi0zArFpL7cY_SGj352xVDniT0zUYBOdeGIkMGBDdAnXt3wiwjvKAqamj4t-V2mq__KJUCKBBWKfhqtM9CffBCl_UuNZEVc_jLBCUXnZibKq39w1A
grant_type authorization_code
redirect_uri http://localhost:62640/Home/CodeFlowCallback
code CfDJ8PM2CeMBx5pBjHhwSA0zkDHar2TV0FSctyNGPhFCU3OgwpZM-0Sycwo8j61Md11VWcP...

If the request is valid, Identify OAuth 2.0 authorization server will return an access_token.

ASP.NET MVC Sample

You can use our web application sample to try the Client authentication out.

A couple of keys were added into the web.config:

To enable the private_key_jwt method, you need to set the "IdentifyOauth2:AuthenticationType" setting to "private_key_jwt" and use a signing certificate's public key to generate a correct client_assertion - a JWT that contains information for client authentication.

You can use our jwks sample for configuring the connection.