Applications

Learn about applications, their types and understand which flow is better suited for you.

Applications in GrantID are meant to correspond to any computer software system that already exist or that will be created. Our job is to make the task of adding authentication/authorization to that system as easy as possible.

Before going any further, is important to state the difference between authorization and authentication:

  • Authorization refers to deciding if someone is allowed to see a resource or perform an action.
  • Authentication refers to determing who is someone as well as retrieving a set of informations about him.

In order to securely perform authorization and authentication we implement the flows determined by the OAuth 2.0 and OpenId Connect specifications.

They consist on procedures that produce Identity and/or Access Tokens. Bellow you can find an example of each of this tokens payloads as defined in the JWT format:

Access Token

{
  "nbf": 1486127410,
  "exp": 1486130410,
  "iss": "https://mysub.grantid.com",
  "aud": "https://mysub.grantid.com",
  "client_id": "my-app",
  "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
  "auth_time": 1486127409,
  "scope": [
    "openid",
    "profile"
  ],
  "amr": [
    "pwd"
  ]
}

Identity Token

{
  "nbf": 1486127418,
  "exp": 1486127718,
  "iss": "https://mysub.grantid.com",
  "aud": "my-app",
  "nonce": "636382263039998929.YTc2NTM0NWQtNjA5Ni00YWE5LTk0NjgtMGZlZWYyZjczYWYxOWE0NTE1MjYtZGRkOS00YmRmLTg3ZjYtNDM3NmZjNDgxMzEy",
  "iat": 1486127417,
  "c_hash": "Rzz43NRKEt5UIFJ6kyJ_jw",
  "sid": "eb051224b1d407911946fe341ccdc769",
  "sub": "26cf5325-23b4-47a3-af5b-a5211e386da8",
  "auth_time": 1486127409,
  "name": "John Doe",
  "email": "john.doe@email.com",
  "phone": "5500000000000",
  "amr": [
    "pwd"
  ]
}

These procedures also determine a way to safely transmit the tokens from the Authentication Provider (GrantID) to your application. Please refer to the Tokens and Scopes page for a more detailed explanation on tokens.

To integrate an application you need to modify it so it performs the following actions:

  1. Token Retrieval: the process in which the application obtains a token for a user or another application. This depends on the type of the application as discussed in the next section.
  2. Token Validation: this process of validating the token by checking the issuer of the token (your subscription url - e.g https://mysub.grantid.com) the required scopes and the integrity of the token. There are several libraries that already implement JWT Validation so you may choose the one you prefer.

Types of Aplications


The types of applications are directly related to the flows they will use to obtain tokens. The supported types are:

  1. Implicit
  2. Code
  3. Hybrid
  4. Resource Owner Password
  5. Client Credentials

Implicit


In this type of application, when a user tries to log in, the application will redirect him to GrantID. The user will provide his email and password if he's already registered or select the "Sign up" option.

After the login, the user is redirected back to your application with the Access and Identity Tokens.

Code


This type of application is very similar to the Implicit option, but, in this case, when the user is redirected back, he receives only a code. This code and a pre-generated Application Secret must be sent to GrantID in order to get the Access and Identity Tokens.

The Application Server must guarantee that the Application Secret is never disclosed. If this condition is met, than this type of application is considered to be significantly more secure than the Implicit variation.

If an application cannot reliably store the Application Secret securely (e.g. Single Page Applications or Mobile Apps) it should use the Implicit type instead.

Hybrid


This type is a combination of the Implicit and Code types. In this mode, the code and the Identity Token are returned to the application upon redirection, so it needs only to validate the Identity Token and exchange the code with the Access Token.

As well as the Code type, this requires that an Application Secret is securely stored by the application.

Resource Owner Password


In this type of application, the user will provide his email and password in the application itself. The application will then call the Resource Password Owner Endpoint on GrantID to validate the credentials and obtain a token.

This type should only be used if the application was built by the same company that owns the GrantID subscription. That is because the user email and password will be entered in the application and so it may be stored or transmitted elsewhere.

Client Credentials


This type of application is intended for Application authentication only. It consists on obtaining an Access Token by providing an Application Id and Secret.

All of the previous types may be combined with the Client Credentials option. This should be used with caution though, as the allowed scopes will be granted to tokens issued by both flows in this scenario.

If you need a different set of scopes to be granted only when the authentication happens via Client Credentials, create a separate GrantID application with the this type only.

The GrantID's own external REST API expects a token obtained by using the client credentials flow, as explained in the documentation.

Application Type Chooser


In order to help you choose the correct type of application for you needs, we have built a simple form that filters you the available options.