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. (NOT YET IMPLEMENTED!!!)

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 application 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. The application does not need to parse its contents.
Refresh token Used in the Authorization Code Flow to get a new access token when the old one expires.

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:

Authorization: Bearer <access_token>

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.

Refresh token

The refresh token will only be available in the Authorization Code Flow which is NOT YET IMPLEMENTED!

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 strongly recommended!
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. Unlike Authorization code flow 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 flow