Articles
Articles

Authentication

Suggest Edits

All requests against the Starmind API need to be authenticated. We use token-based authentication, where you receive a unique token after successfully logging in. This token is tied to your user and can be used as a "passport" in all subsequent requests until it expires.

OAuth 2.0 Authorization Code Grant Flow

Use the OAuth 2.0 Authorization Code grant flow for all types of integrations where you want your application (client) to consume the Starmind API on behalf of a Starmind user. This type of authorization flow is typically used with mobile apps or other integrations that have a backend (server) component.

Use this method if you are in an environment where you can store user credentials securely. Do not use the reauthorization code grant flow for client-side JS applications.

How does it work? When the user authorizes the application (client), they are redirected back to the app with a temporary code in the URL. The application exchanges that code for the access token. When the application makes the request for the access token, that request is authenticated with the client secret, which reduces the risk of an attacker intercepting the authorization code and using it themselves. This also means the access token is never visible to the user, so it is the most secure way to pass the token back to the application, reducing the risk of the token leaking to someone else.

  1. Reach out to Starmind to get your credentials for the Oauth Client (app). You need to provide the redirect URL Starmind should whitelist. You will get from Starmind the following: Authentication Host, Realm Id and Client Id

  2. Your application should redirect the user to the following URL

https://<authentication-host>/auth/realms/<realm_id>/protocol/openid-connect/auth?client_id=<client_id>&response_type=code&redirect_uri=<redirect_uri>

  1. Next, the user needs to sign in.

  2. As soon as the user is signed in, the user is redirected back to the provided redirect_uri. In the URL parameters, you find the code you require for the next step.

  3. The provided code can now be exchanged for an access and refresh token

POST /auth/realms/<realm-id>/protocol/openid-connect/token HTTP/1.1
Host: <authentication-host>
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
grant_type=authorization_code&
code=<code>&
redirect_uri=<redirect_uri>

Try it out with Curl

curl --request POST 'https://<authentication-host>/auth/realms/<realm-id>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'code=<code>' \
  --data-urlencode 'redirect_uri=<redirect_uri>'

OAuth 2.0 Password Grant Flow

The Oauth 2.0 Password grant flow is used when the application (client) exchanges the user’s username and password for an access token. This is exactly the thing OAuth was created to prevent in the first place, so you should be careful with this flow and only use it for very specific use-cases e.g. if you want to perform actions with a dedicated technical user.

Some customers do integrate this flow for server-to-server integrations where they are limited in options and cannot use the Authorization Code flow.

  1. Reach out to Starmind to get your credentials for the Oauth Client (app). You need to provide the redirect URL Starmind should whitelist. You will get from Starmind the following: Authentication Host, Realm Id and Client Id

  2. With those credentials, you can now login to the API of Starmind:

POST /auth/realms/<realm-id>/protocol/openid-connect/token HTTP/1.1
Host: <authentication-host>
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=<client_id>&
username=<email>&
password=<password>&
scope=email profile

Try it out with Curl

curl --request POST 'https://<authentication-host>/auth/realms/<realm-id>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'username=<email>' \
  --data-urlencode 'password=<password>' \
  --data-urlencode 'scope=email profile'
  1. Within the response, you find the access_token. The token can use this to authenticate your requests with the API. Send it as a Bearer Token in the Authrization header. 
GET /api/v1/users/me HTTP/1.1
Host: <host>
Authorization: Bearer <accessToken>

OAuth 2.0 Token Exchange to act on behalf of other users

Starmind supports user impersonation with the OAuth 2.0 Token Exchange grant. This method allows applications (clients) or a technical user with the appropriate role to access resources and perform actions in Starmind on behalf of other users.

This type of authorization flow is typically used with integrations that have a backend (server) component.

  1. Reach out to Starmind to get the access credentials for your instance. You will need the following:

    • Application host
    • Authentication host
    • Realm id
    • Client id
    • Client secret

  2. With those credentials, you can now login to the API of Starmind:

POST /auth/realms/<realm-id>/protocol/openid-connect/token HTTP/1.1
Host: <authentication-host>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<client_id>&
client_secret=<client_secret>
  1. With the proper access token, you now are able to request a token for a specific user. In the "requested_subject" you can provide the email address or the idp-user-id. 
POST /auth/realms/<realm-id>/protocol/openid-connect/token HTTP/1.1
Host: <authentication-host>
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
client_id=<client_id>&
client_secret=<client_secret>&
subject_token=<access_token>&
requested_subject=<email_adress or idp_user_id>

Try it out with Curl

curl --request POST 'https://<authentication-host>/auth/realms/<realm-id>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'client_secret=<client_secret>' \
  --data-urlencode 'subject_token=<access_token>' \
  --data-urlencode 'requested_subject=<email_adress or idp_user_id>'
  1. Now, you can use the access token from the second request to make the request on behalf of that user.
GET /api/v1/user/me HTTP/1.1
Host: <host>
Authorization: Bearer <accessToken>

Refresh the Access Token

As soon as the token is no longer valid, you can refresh it with the "refresh_token".

POST /auth/realms/<realm-id>/protocol/openid-connect/token HTTP/1.1
Host: <authentication-host>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<refresh_token>&
client_id=<client_id>

Try it out with Curl

curl --request POST 'https://<authentication-host>/auth/realms/<realm-id>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'refresh_token=<refresh_token>'

Updated 6 months ago