Client Authentication

Description of client authentication in REST API requests

Client authentication in OAuth2 and thus HyperID is a critical security feature that ensures that only authorized clients can access protected resources. There are several methods for client authentication, including client secret, JWT bearer token, mutual TLS, etc.

Each has its own strengths and weaknesses. The choice of method depends on the specific requirements of the authorization server and the client. However, we suggest using Client Assertion as a default method.

Client Secret method is the simplest one and involves the client sending a client ID and client secret in the request header to the authorization server. The client secret is a unique string generated by the authorization server during the client registration process.

POST /token HTTP/1.1
    Host: server.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
        code=i1WsRnuB1&
        redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&
        client_id=s6BhdRkqt3&
        client_secret=PHNhbWxw01

The basic authentication scheme assumes that the client provides credentials (client ID and client secret) in plaintext, which are encoded using Base64 encoding and sent to the server in the authorization header. The server then verifies the credentials against the pre-existing client database and grants access to the resource if the credentials are valid.

POST /token HTTP/1.1
    Host: server.example.com
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
    
    grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
        &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&

The use of both of the above methods is limited because of insufficient security and interception vulnerability (credentials are transmitted in clear text). To mitigate this risk, HyperID uses HTTPS to transmit customer credentials securely.

Client Assertion

We recommend to use the Client Assertion method.

A Client Assertion is a signed and encoded assertion sent by the client application to the authorization server along with an access token request. The assertion contains information that proves the client's identity, such as its client ID and a private key. The authorization server verifies the client assertion to ensure that it is valid and issued by the proper client. If the assertion is valid, the authorization server issues an access token to the client application.

HyperID supports two scenarios for creating a client assertion:

1. Using the HMAC SHA algorithm (e.g., HMAC SHA-256), where the HMAC (Hash-based Message Authentication Code) is computed using the UTF-8 octets of the client_secret representation as the shared key.

2. Using certificates, where HyperID obtains the client's public certificate during client’s registration, and the client itself uses its private key to sign the assertion.

POST /token HTTP/1.1
    Host: server.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
        code=i1WsRnuB1&
        redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&
        client_id=s6BhdRkqt3&
        client_assertion_type=
        urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
        client_assertion=PHNhbWxwol ... ZT