Docs

Hydda Connect

API Reference

This document describes the Oauth2 endpoints implemented by Hydda IdP and their use-cases with examples.

Environments

Endpoints

Each topic describes the endpoint and how to use it. The endpoints are listed below.

Hydda IdP only support the Authorization Code Grant flow

EndpointDescriptionDocumentation
/oauth2/authorizeAuthorize endpointLink
/oauth2/tokenToken endpointLink
/oauth2/userinfoUserInfo endpointLink
/.well-known/openid-configuration Try it outConfiguration endpointLink
/.well-known/jwks.json Try it outJWKS endpointLink

Supported flows

  • Authorization Code Flow
    • Used for clients
  • Client Credentials Flow
    • Used for server to server communication
  • Refresh Tokens
    • Used to get new access tokens without user interaction

Token specification

In the background, Hydda IdP uses AWS Cognito to store user credentials and perform authentication. This means our tokens conform to AWS Cognito's specification with some additional data that we append.

Id token

The Id token is always returned from the token endpoint. The id token contains claims to authenticate a user.

Example Id token.

{
  "sub": "<cognito-userid>",
  "cognito:groups": [],
  "iss": "https://cognito-idp.eu-north-1.amazonaws.com/eu-north-1_8xnGNQwmm", // Verify this against the issuer in the configuration endpoint
  "cognito:username": "<cognito-userid>",
  "aud": "h5kf02c1j7l1tuhtnplbun48f", // This is the clientId that this token is issued for
  "hydda:tenant-id": "b11ed205-ec51-4d0a-ab2d-c163407fcfe5", // The tenant this user belongs to in Hydda Cloud
  "hydda:user-id": "1bafc98e-5c92-4ec1-8b7d-e756218a06c9", // Hydda Clouds userId for this user
  "email": "patrik.nyman@hyddagroup.com"
  // ... additional default claims
}
ClaimDescription
subThe Cognito user id - this is the internal userid in Cognito - NOTE! Do not use this to uniquely identify a user
cognito:usernameSame as subject
audThe client id that this token is issued for - you should verify that this matches the clientId you've been assigned
hydda:tenant-idThe tenant id that this user belongs to in Hydda Cloud
hydda:user-idThe user id that this user belongs to in Hydda Cloud - NOTE! Use this to uniquely identify a user

Access token

We provide an access token that can be used to

FAQ

Why not use subject/cognito:username

Hydda IdP is a IdP broker, this means we're utilizing a third party IdP to authenticate users. This means we cannot guarantee that the subject/cognito:username is unique across all IdP's. So internally we assign our own unique id to all users, which we call "hydda:user-id" in our claims.

We guarantee that "hydda:user-id" never change and you can safely use this Id to uniquely identify a user.

cognito:groups claim looks weird

Due to limitations in Cognito we cannot append claims to our own access tokens except for group claims. To solve this internally we use cognito:groups claim to store our own claims. This means that the cognito:groups claim will contain more then just groups.

At the moment this leaks into our Id token, you can ignore these.

Can I just match email = email in my own system?

No

The email claim is not guaranteed to be unique. We do our best to enforce this but due to the complexity of federating with other IdP's we cannot guarantee this.
We guarantee that the hydda:user-id can uniquely identify a user.

If you want to do a email matching strategy, you MUST use the hydda:tenant-id claim to scope the email to a tenant. While this is not 100% secure, it at least reduces the surface to within a tenant and not across your entire system.

Authorize endpoint

The /oauth2/authorize endpoint is a redirection endpoint that initiates the authentication flow. It redirects to the Login endpoint with the parameters that you included in your request.

To use the authorize endpoint, invoke your user's browser at /oauth2/authorize with parameters that provide your user pool with information about the following user pool details.

  • The app client that you want to sign in to.
  • Callback URL that you want to end up at after a successful login

You can also supply a state and code challenge parameters to the authorize endpoint. The state parameter is used to prevent cross-site request forgery attacks. The code challenge parameter is used to prevent code injection attacks.

NOTE! We enforce the code challenge, which means you are required to use this when using the authorize endpoint. This flow is usually named a PKCE flow.

GET /oauth2/authorize

The /oauth2/authorize endpoint only supports HTTPS GET. Your app typically initiates this request in your user's browser. You can only make requests to the /oauth2/authorize endpoint over HTTPS.

Request parameters

ParameterRequiredDescription
client_idYesThe app client ID. Provided to you by Hydda
response_typeYesThe response type. Must be code. Allowed values are: code
redirect_uriYesThe URL to redirect to after a successful login. Must be registered with Hydda
code_challengeYesThe code challenge. Must be a Base64 SHA256 hash of the code verifier or a plain text depending on the choice of code_challenge
code_challenge_methodYesThe code challenge method. Must be S256 or plain
stateNoA value that is returned in the callback URL. Used to prevent cross-site request forgery attacks

Example request

GET https://idp.dev.hydda.cloud/oauth2/authorize?
                                 client_id=<your-client-id>&
                                 response_type=code&
                                 redirect_uri=<your-callback-uri>&
                                 code_challenge=<your-code-challenge>&
                                 code_challenge_method=S256&
                                 state=<optional-state>

If the request is valid, Hydda IdP will redirect the user to the login endpoint. The login endpoint will then redirect the user back to the callback once the users is authenticated.

Token endpoint

The /oauth2/token endpoint is used by the client to obtain an id token by presenting its authorization grant or refresh token. The /oauth2/token endpoint only supports HTTPS POST. You can only make requests to the /oauth2/token endpoint over HTTPS.

We do not recommend calling this endpoint directly through your users browser but instead call this endpoint from your backend. If direct browser access is required, you'll need to discuss this with Hydda since this is not a default option.

POST /oauth2/token

Request parameters in header

ParameterRequiredDescription
Content-TypeYesThe content type. Must be application/x-www-form-urlencoded
AuthorizationNoThe client ID and client secret separated by a colon, encoded in Base64, for example, dGVzdDp0ZXN0. Required if you don't use the "body method"

Request parameters in body

ParameterRequiredDescription
grant_typeYesThe grant type. Must be authorization_code or refresh_token
codeYesThe authorization code that is returned from the authorize endpoint. Used if grant_type is 'authorization_code'
redirect_uriYesThe URL to redirect to after a successful login. Must be registered with Hydda. Used if grant_type is 'authorization_code'
code_verifierYesThe proof key. Used if grant_type is 'authorization_code'
refresh_tokenYesThe refresh token that is returned from the token endpoint. Used if grant_type is 'refresh_token'
client_idNoThe app client ID. Required if you don't use the "Authorization" header.
client_secretNoThe app client secret. Required if you don't use the "Authorization" header.

Example request

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token&
                            grant_type=authorization_code&
                            client_id=<your-client-id>&
                            code=AUTHORIZATION_CODE&
                            redirect_uri=<your-callback-uri>
    -H Content-Type='application/x-www-form-urlencoded' -H Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

Example response

HTTP/1.1 200 OK   
Content-Type: application/json
{ 
"access_token":"eyJra2example", 
"id_token":"eyJra2example",
"refresh_token":"eyJj3example",
"token_type":"Bearer", 
"expires_in":3600
}

UserInfo endpoint

TODO: Write userinfo documentation

Configuration endpoint

The /.well-known/openid-configuration endpoint returns information about the IdP service. The information returned includes the endpoints where the service accepts requests from clients.

GET /.well-known/openid-configuration

The /.well-known/openid-configuration endpoint only supports HTTPS GET. You can only make requests to the /.well-known/openid-configuration endpoint over HTTPS.

JWKS endpoint

The /oauth2/jwks endpoint returns the JSON Web Key Set (JWKS) document. The JWKS document contains the public keys used by the IdP service to sign JWT tokens.

GET /oauth2/jwks

The /oauth2/jwks endpoint only supports HTTPS GET. You can only make requests to the /oauth2/jwks endpoint over HTTPS.

Example flow

Login

Login flow

Steps

  1. The client redirects the user to the authorize endpoint
  2. The authorize endpoint redirects the user to the login endpoint and Hydda IdP displays the login page and authenticates the user
  3. Hydda IdP redirects the user back to the authorize endpoint with the authorization code
    1. Example redirect https://<your-callback-uri>&code=<authorization-code>&state=<optional-state>
  4. The client calls the token endpoint with the authorization code and code verifier
  5. The token endpoint returns the access token and refresh token
  6. When the access_token expires the client calls the token endpoint with the refresh token

Refresh token

TODO: Currently we include this in the login picture

On this page