NAV

Authentication to Giosg

Giosg uses an OpenID Connect compatible authentication flow based on OAuth2.

There are two supported authentication flows, as described by OpenID Connect specification:

Getting started

To add Giosg authentication to your app, you first need to create a Giosg account, if you don’t already have one, and then register a new Giosg App! Your app ID will be the client ID discussed in this documentation.

You also need to add at least one “redirect URI” to you Giosg App. These are addresses in your app for receiving authentication responses from Giosg, as discussed later.

Tokens

There are multiple types of tokens used for authentication and authorization of a user, as specified by OpenID Connect and OAuth2. Here’s a short summary of all of them.

Token Description
ID token Includes identification information of the authenticated user, as a JSON Web Token. This is meant for the app for receiving basic information about the user (and verifying its validity). E.g. to show some basic information about them in the UI.
Access token Used to authorize requests to Giosg HTTP API and Real-time API as the authenticated user. It’s format depends on what authentication flow was used to request it.

ID token

The ID token is encoded as JSON Web Token (JWT). Your web app can decode this token and extract the included data object. The object will contain attributes called “claims”. These claims contain useful information about the user who is being authenticated, such as the name and email address.

The following claims are available:

Claim Type Description
iss string Which URL issued the token (https://service.giosg.com/identity/authorize)
sub string The ID of the user, as an UUID (e.g. 7ce5ccdb-aa0f-470d-ad49-240448aba6a0)
aud array of strings An array with exactly one string that matches the provided client_id, i.e the ID of the Giosg App
exp integer Expiration time on or after which the ID Token is no longer valid. Its value is a number of seconds from 1970-01-01T00:00:00Z as measured in UTC.
iat integer Time at which the token was issued. Its value is a number of seconds from 1970-01-01T00:00:00Z as measured in UTC.
nonce string The nonce parameter from the authentication request unmodified. Your web app should check that this matches the one you provided, to mitigate replay attacks.
org string The ID of the user’s organization, as an UUID (e.g. 8f20a18f-7fb2-474a-aca0-ff4dd608ffc3)

If the ID token was requested with an profile scope, the following claims will be included as well:

Claim Type Description
name string The full name of the user
given_name string The first name of the user
family_name string The last name of the user
picture string Full URL to the user’s avatar, if any

If the ID token was requested with an email scope, the following claims will be included as well:

Claim Type Description
email string The email of the user
email_verified boolean Whether or not the email address has been verified

Access token

Example authorization header

Authorization: Bearer 1234567890abcdefghijklmnopqrstuvwxyz

The access token is used with Giosg HTTP API requests and Real-time API WebSocket connections.

With HTTP API requests, you include the token to the Authorization header of every request. If received with Implicit flow, it is used with a Bearer word in the Authorization header.

Authorization: Bearer <access_token>

If received with an Authorization Code Grant Flow, it is used with a Token word:

Authorization: Token <access_token>

Always use the word from the token_type attribute before the access token in the Authorization header!

For more information, see the Authorization with an access token.

For information how to use the access token with WebSocket connections, see Connecting to WebSocket.

Implicit Flow

Implicit authentication is suitable for front-end web applications that use the APIs directly from the browser (or, in technical terms, in the “User Agent”).

Giosg authentication Implicit Flow

The authentication process should go like this:

  1. The user opens the web app in the browser (e.g. https://example.com/)
  2. The web app checks if the user is already authenticated by checking if there is an existing access token stored in the local/session storage. If already authenticated, the authentication flow can be skipped.
  3. The UI shows the “Sign in” link or button
  4. User clicks the “Sign in” button
  5. User’s browser is redirected to the authentication URL (https://service.giosg.com/identity/authorize?…) with an authentication request.
  6. User submits their username and password, if they are not already signed in to Giosg
  7. User’s browser is redirected back to the service’s redirect URI with an authentication response.
  8. The web app checks if the URI hash indicates an error, and that the state matches the one sent in the authentication request
  9. The web app parses the access_token and the id_token from the URI hash and persists them to local/session storage
  10. The web app decodes the user’s name from the ID token (which is JWT) and shows it in the UI, as well as the “Sign out” button
  11. The web app includes Authorization: Bearer <access_token> header to every AJAX request made to Giosg HTTP APIs.
  12. When the token(s) are about to expire, or when an API request is responded with 401 Unauthorized, the web app needs to refresh the token. With Implicit Flow, there are two options:

Authentication request with Implicit Flow

Example authentication request with redirect URI https://client.example.org/my_callback

https://service.giosg.com/identity/authorize?response_type=id_token%20token&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fclient.example.org%2Fmy_callback

An authentication request is an OAuth 2.0 Authorization Request done by the service to the Giosg’s authorization server.

With Implicit Flow, the request is done with HTTP GET request to the following endpoint. In practice this is done by navigating the user’s browser window to the request URL:

GET https://service.giosg.com/identity/authorize

The endpoint requires several parameters, which must be encoded with URI Query String Serialization.

The following parameters exist:

Parameter Required Description
scope required A list of “scope” strings separated by single whitespace characters. At least one of them must be openid. Other supported values are profile and email. The selected scopes affect the information included to the ID token. For example, to request user’s basic info, you could use openid profile and to request email as well, you could use openid profile email. Remember to encode whitespaces, so an actual parameter would look like openid%20profile%20email.
response_type required With Implicit Flow this needs to be id_token token for receiving both ID and access tokens, or id_token for just the ID token. Note that in id_token token the words are separated by whitespace, and when included in the URI, the it must be encoded as id_token%20token
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth “client”. The ID is in UUID format.
redirect_uri required Redirection URI to which the response will be sent. This must exactly match one of the URIs that you have allowed for your Giosg App! The https scheme is required!
nonce required The value that will be included unmodified as the nonce claim in the ID token. The value should be used to associate a client session with an ID Token, and to mitigate replay attacks.
state recommended Opaque value used to maintain state between the request and the callback. It will be sent back as-is in the authentication response. Recommended to prevent Cross-Site Request Forgery (CSRF, XSRF).
prompt optional If you provide value none then no authentication UI will be shown to the user. Instead an error authentication response is sent back if the user is not already logged in with valid session. Useful for “silent refresh”. You can also use value login which will show the login UI even if the user already has a valid session.

Authentication response with Implicit Flow

Example of a successful authentication response URI

https://client.example.com/my_callback#token_type=bearer&id_token=12345abcdef&access_token=67890ghijklmn&expires_in=3600&state=st4t3F0rCsRf

When the user has completed the authentication process, the Giosg authentication service redirects the user to the provided redirect_uri. For example:

The URI hash (after #) describes if the request was successful or not, and it will also contain the tokens for the application’s use.

Response parameters are formatted in the same way than URI query parameters. All the values are encoded with URI Query String Serialization so you must decode them before use. Otherwise you might get invalid results.

For a successful authentication, the following parameters are included to the hash:

Parameter Description
token_type This value is always bearer
access_token The access token that the app can use with APIs. Its lifetime is specified by expires_in parameter. It is returned only if response_type request parameter was id_token token
id_token The ID token as a JSON Web Token that the app can decode and get verified user information.
state The request state parameter unmodified. Your app must verify that the value matches the one sent with the request in order to prevent CSRF attacks.
expires_in The number of seconds the access token is valid since the request was generated. After this the APIs won’t accept the token and you need to retrieve a fresh token.
socket_url The base URL for a WebSocket connection that client can use to subsribe real-time changes. See below for usage instructions!

Example WebSocket URL after appending the access token

wss://messagerouter.giosg.com/websocket?token=67890ghijklmn

In addition to traditional response parameters, successful responses contain a socket_url parameter. It describes the base URL that the client can use to connect with WebSocket for subscribing real-time changes. For example: wss://messagerouter.giosg.com/websocket. For more information see WebSocket API documentation.

Before connecting to WebSocket URL, the client MUST append the access_token as a token URL parameter. The client MUST ensure that the parameter is correctly appended even if the URL already contains parameters! In other words, you need to append either ?token=MY_ACCESS_TOKEN or &token=MY_ACCESS_TOKEN depending on whether or not the URL already contains character ?.

If the authentication is not successful, then the response contains the following parameters:

Parameter Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII
state The value of the state parameter included in the Authentication Request

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg’s internal client).
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
interaction_required User’s interaction of some form to proceed and the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for user’s interaction.
login_required User needs to authenticate but the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for entering user’s credentials.

Silent access token refresh with Implicit Flow

Silent token refresh

When the access token expires, you need to retrieve a new one in order to continue using APIs. Implicit Flow does not support refresh tokens. You need to refresh the token by performing another authentication request.

There are several methods how this re-authentication request could be done. An easiest solution is to automatically navigate user’s browser to the identity service for re-authentication. However, this would have very distruptive impact on the user experience. Another method would be to perform the re-authentication in pop-up window, but in practice this has a limitation that it can only be done on user’s interaction on the web page (e.g. click an element) in order to avoid pop-up blockers. This would also be distruptive for the user.

A better solution is to use a silent refresh by running the re-authentication in an invisible iframe element. It works like this:

  1. The web app creates an invisible iframe that navigates to the authentication request URL with an additional parameter prompt=none
  2. The identity service re-authenticates the user if possible without showing an user interface
  3. The identity service redirects the iframe to a redirect_uri page hosted by the web app
  4. The page in the iframe sends the result (new access token or error) to the parent page
  5. The main web app page receives the result from the iframe and stores the new token
  6. The iframe is removed from the element

The prompt=none parameter will tell the identity service to not show any user interface but instead redirect back with an error if the user cannot be re-authenticated without an UI. For example, the user’s session has expired on the identity service, or the user is required to re-enter their password.

If the silent refresh fails due to not able to show an UI for the user, the web app could then display an message that the user needs to re-authenticate and provide a link which starts the re-authentication in a traditional way, in the browser window or in a pop-up.

The silent refresh method requires that the web app hosts a separate web page used as redirect_uri. The page is typically blank (as it won’t be visible to the user) and contain a short script that delivers the re-authentication result to the parent frame (where the actual web app is running).

However, to make things easier, Giosg provides an useful Authentication Callback page that you can use instead of implementing your own redirect landing page.

Authentication Callback Page

The Authentication Callback Page is an helpful service that you may use instead of implementing your own redirect URI for your web app when performing an Implicit Flow authentication in an pop-up or in an iframe.

The Authentication Callback page will use JavaScript’s cross-origin messaging (Window.postMessage()) to send the authentication result (the URI hash) to your web app, which your web app can then parse like with traditional authentication. For security, the message will always be sent to the specific origin that you must specify beforehand.

The Authentication Callback Page URI has the following format:

https://service.giosg.com/identity/callback?target=parent&origin=YOUR_ORIGIN&client_id=YOUR_CLIENT_ID

The parameters are:

Parameter Required Description
target required To which frame the results will be sent. Either parent when used in an iframe, or opener when used in a pop-up window.
origin required The origin of your web app, used as the targetOrigin parameter for the Window.postMessage call. The wildcard origin (*) is not allowed for security reasons.
client_id required The ID of your Giosg App as registered to Giosg. Matches the client_id parameter in the authentication request.

When the page is loaded, it will send the following message to the parent frame or the opener page:

giosg-auth-callback:#token_type=bearer&id_token=12345abcdef&access_token=67890ghijklmn&expires_in=3600&state=st4t3F0rCsRf

Your app should filter only messages that starts with giosg-auth-callback:. Everything after this should be considered equal to the URI hash sent with the authentication response.

Here’s how you enable the Authentication Callback Page for your web app:

  1. Determine your web app’s origin, including protocol, host name and any port number, e.g. https://client.example.com
  2. Build your Authentication Callback URI as described above (remember URI encoding), e.g. https://service.giosg.com/identity/callback?target=parent&origin=https%3A%2F%2Fclient.example.com&client_id=5a8a201f-6999-462b-b4a2-bb08df897321
  3. Register this URI as one of the allowed redirect URIs for your web app
  4. When building re-authentication request URI, use this as an redirect_uri parameter (remember URI encoding again) for the authentication request URI, e.g. https://service.giosg.com/identity/authorize?response_type=id_token%20token&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fservice.giosg.com%2Fidentity%2Fcallback%3Ftarget%3Dparent%26origin%3Dhttps%253A%252F%252Fclient.example.com%26client_id%3D5a8a201f-6999-462b-b4a2-bb08df897321
  5. Register an message event handler for your web app’s Window object
  6. Create an hidden iframe and use this URI as the src attribute for it
  7. Wait for the iframe to send a message to your web app (starting with giosg-auth-callback:)
  8. Strip the giosg-auth-callback: prefix from the message and parse the authentication response from the rest of the string
  9. If the response contains an error, show a message to the user prompting them to re-authenticate themselves

Authorization Code Grant Flow

Authorization Code Grant Flow is used by apps and integrations running on the servers. It supports performing “offline” requests as a user (user is not logged in giosg system). For example, your server might run some periodical task or react to some trigger from an integrated system, and you then want to perform actions in behalf of the user.

The downside with this approach is that you need a server-side application that communicates with the giosg HTTP APIs securely, without exposing secrets or access tokens to the client side. The process also involves additional steps to ensure the security of the token. As an upside, the access token you receive does not expire (but may be revoked) so you can store it securely to your app’s database without a need to refresh it.

Giosg authentication Authorization Code Grant Flow

The authentication process should go like this:

  1. The user opens the app in the browser (e.g. https://example.com/)
  2. The app checks if it has a valid session for an authenticated user. This has be done by the app provider by using some session authentication. If they are already logged in, it can skip the authentication flow.
  3. The UI shows the “Sign in” link or button
  4. User clicks the “Sign in” button
  5. User’s browser is redirected to the authentication URL (https://service.giosg.com/identity/authorize?…) with an authentication request.
  6. User submits their username and password, if they are not already signed in to Giosg
  7. User’s browser is redirected back to the service’s redirect URI with an authentication response.
  8. The app checks if the URI query indicates an error, and that the state matches the one sent in the authentication request
  9. The app server parses the code from the URI
  10. The app server exchanges the code to the actual access token by making a server-side access token request to https://service.giosg.com/identity/token?… using its app ID and app secret
  11. The app server receives an access_token (and possibly the id_token) for the user and persists it securely to its database.
  12. When the app wants to retrieve information or perform actions in behalf of the user, it makes server-side request to the giosg HTTP API including Authorization: Token <access_token> header

Authentication request with Authorization Code Grant Flow

Example authentication request with redirect URI https://client.example.org/my_callback

https://service.giosg.com/identity/authorize?response_type=code&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fclient.example.org%2Fmy_callback

An authentication request is an OAuth 2.0 Authorization Request done by the service to the Giosg’s authorization server.

With Authorization Code Grant Flow, the request is done with HTTP GET request to the following endpoint. In practice this is done by navigating the user’s browser window to the request URL:

GET https://service.giosg.com/identity/authorize

The endpoint requires several parameters, which must be encoded with URI Query String Serialization.

The following parameters exist:

Parameter Required Description
scope required A list of “scope” strings separated by single whitespace characters. At least one of them must be openid. Other supported values are profile and email. The selected scopes affect the information included to the ID token. For example, to request user’s basic info, you could use openid profile and to request email as well, you could use openid profile email. Remember to encode whitespaces, so an actual parameter would look like openid%20profile%20email.
response_type required With Authorization Code Grant this needs to be code.
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth “client”. The ID is in UUID format.
redirect_uri required Redirection URI to which the response will be sent. This must exactly match one of the URIs that you have allowed for your Giosg App! The https scheme is required!
nonce required The value that will be included unmodified as the nonce claim in the ID token. The value should be used to associate a client session with an ID Token, and to mitigate replay attacks.
state recommended Opaque value used to maintain state between the request and the callback. It will be sent back as-is in the authentication response. Recommended to prevent Cross-Site Request Forgery (CSRF, XSRF).
prompt optional If you provide value none then no authentication UI will be shown to the user. Instead an error authentication response is sent back if the user is not already logged in with valid session. You can also use value login which will show the login UI even if the user already has a valid session.

Authentication response with Authorization Code Grant Flow

Example of a successful authentication response URI

https://client.example.com/my_callback?code=123456789abcdefghij&expires_in=3600&state=st4t3F0rCsRf

When the user has completed the authentication process, the Giosg authentication service redirects the user to the provided redirect_uri. For example:

The URI query (after ?) describes if the request was successful or not, and it will also contain the code that the app can exchange for the access token.

Response parameters are encoded with URI Query String Serialization so you must decode them before use. Otherwise you might get invalid results.

For a successful authentication, the following parameters are included as query parameters:

Parameter Description
code The authorization code that the app can exchange to the access token.
state The request state parameter unmodified. Your app must verify that the value matches the one sent with the request in order to prevent CSRF attacks.

Contents of code parameters are following:

Parameter Description
jti Unique identifier for the code.
iat When the token was issued.
exp Expiration time for the token, valid for a very short time.
aud List of target audiences for these specific URLs. It is not accepted by any other API nor message router. This is always [https://service.giosg.com/identity/token].
iss Issuer of the code. This is always https://service.giosg.com/identity/authorize.
user_id ID of the user for his code can be used to get access token for. It is for this user ONLY and therefore it does not have permissions for other users’ users prefixed APIs.
organization_id ID of the user’s organization.
app_id ID of the app. Only this app is allowed to exchange this code to an access token.

If the authentication is not successful, then the response contains the following parameters:

Parameter Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII
state The value of the state parameter included in the Authentication Request

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg’s internal client).
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
interaction_required User’s interaction with some form is required to proceed and the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for user’s interaction. One of these forms might be e.g. expired password.
login_required User needs to authenticate but the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for entering user’s credentials.

Token request with Authorization Code Grant Flow

Example Token request with for an app with ID 2ac428cd-7fe2-43a0-bd6f-bb747f138ef9&

POST /identity/token HTTP/1.1
Host: service.giosg.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
  code=i1WsRn1uB1d9s8Xs89jf2la9i9d8fj9838&
  client_id=2ac428cd-7fe2-43a0-bd6f-bb747f138ef9&
  client_secret=2348523ui4u2349823h42938h42384h

A Token request is an OAuth 2.0 Authorization Request done by the service to the Giosg’s authorization server. It is used to exchange an Authorization Code to a persistent access token.

With Authorization Code Grant Flow, the request is done with HTTP POST request to the following endpoint:

POST https://service.giosg.com/identity/token

The endpoint requires several parameters in the payload (which must be encoded in application/x-www-form-urlencoded):

Parameter Required Description
grant_type required This must be exactly authorization_code
code required This is the Authorization Code that will be exchanged to an access token.
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth “client”. The ID is in UUID format.
client_secret required The secret string generated to your app and only known by your app!

Token response with Authorization Code Grant Flow

Example of a successful Token response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdhbml6YXRpb25faWQiOiIzMjQ3NTVjNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJzY29wZXMiOltdLCJ2ZXJzaW9uIjoyLCJqdGkiOiIzMjc2OGNmNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJhdWQiOlsidGVzdG1lc3N1IiwidGVzdHNlcnZlciJdLCJleHAiOjE1NDUyNTEzNjYsInVzZXJfaWQiOiIzMjUzYjdiYy0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJpc3MiOiJodHRwOi8vdGVzdHNlcnZlci9pZGVudGl0eS9hdXRob3JpemUiLCJpYXQiOjE1NDUyMDgxNjYuOTYyMzQsImFwcF9pZCI6bnVsbH0.949TQOro7yxwwYN-S1AQ4_Jcm5vMM0O07pHyiWysE1U",
    "token_type": "Token",
    "user_id": "d0daa859-645a-4953-a089-1951c913ca30",
    "organization_id": "365a9781-de37-4872-95e9-088ecbbd1111",
    "app_id": "e287032d-4898-4e1d-8da8-f2e51cc0e023"
}

If the code is valid and the app’s client credentials are valid, then the API endpoint returns a JSON-encoded object as a payload. For a successful exchange, the following attributes are present in the response payload:

Attribute Description
access_token The access token (an “API key”) that can be used to authorize API requests.
token_type Tells which keyword you must use in the Authorization header of your following API requests as a prefix for the access token. Currently, this value is always Token.
user_id ID of the user to which the access token grants an access
organization_id ID of the organization in which context the access token allows API requests
app_id ID of your app, matching the client_id that was defined as a parameter

If the authentication is not successful, then the status code is 400, and the response contains the following attributes:

Attribute Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg’s internal client, or non-matching app secret).