Products » Connect2id server » Documentation » Guides »

How to implement custom OAuth 2.0 grants

Try using a standard OAuth grant if possible

We generally advise against implementing custom OAuth 2.0 grants for letting client applications obtain tokens. Try to see if your use case can fit one of the standard grants developed by the OAuth working group, which cover a range of scenarios and quite importantly, have been thoroughly reviewed by experts in the field.

The Connect2id server supports all OAuth grants that have been made standard at the time of writing this document. A number of other grants forare in development at the OAuth working group.

If you're unsure which OAuth grant to choose for a particular scenario, feel free to contact Connect2id support.

Using the direct authZ endpoint for obtaining tokens for custom grants

If you need to implement a custom OAuth grant, e.g. for legacy purposes, use the direct authorisation endpoint of the Connect2id server. This is a special protected endpoint, not accessible to normal clients, for minting identity, access and refresh tokens with the desired parameters.

  • Set up a proxy or web service that intercepts HTTP requests to the token endpoint of your Connect2id server.

  • Parse the incoming token requests to find out the OAuth grant type (grant_type).

  • If the grant type doesn't match the custom one, just forward the HTTP request without modification to the token endpoint of the Connect2id server.

  • If the grant type matches the custom identifier, e.g. urn:example:params:oauth:grant-type:xyz:

    • Ensure the validity of the client_id and if the client is confidential, authenticate it. The client details can be obtained with a read call to the client registration URL.
    • Parse and validate the custom grant according to its rules.
    • If the custom grant is valid, make a request to the direct authorisation endpoint to get the desired tokens.
    • Return the tokens in a HTTP response to the client.

You can use the open source OAuth 2.0 SDK to implement some of the steps above, like getting a client's registration and constructing the token response.