Nylas Identity

SDK to handle uas sessions & auth

Introduction

Nylas Identity is used to handle OAuth flow requests & sessions from UAS to the JS client

Table of content

• Install
• Initialization
  • Session config
• Code challenge generation
• Code exchange flow
• API
  • auth
    • Config
  • authIMAP
    • Payload
    • Responses
  • isLoggedIn
  • detectEmail
    • Responses
  • applicationInfo
    • Responses
  • getAvailableProviders
    • Responses
  • getProfile
  • getScopes
  • validateToken
  • logout
  • Events

Install

TODO

Initialization

When initialized the NylasSessions

const session = new NylasSessions({
  ClientID: "example_id",
  RedirectURI: "http://localhost:3000/",
});

Session config

Session config is used to init the identity library

Prop name	Type	Required	Description
ClientID	string	true	Nylas Client ID
RedirectURI	string	true	RedirectURI of your app
AccessType	string	false	Type of access you request from token (defaults to offline)
Domain	string	false	Your Nylas Auth domain
Store	Store	false	Set a store for handling sessions (defaults to localStorage)
Hosted	boolean	false	Set if you want to use hosted page instead of your own implementation

Code challenge generation

Nylas Identity generates a PKCE code on the fyl upon initialization inside localStorage. If the user has no ongoing session & code is not present inside storge it generates a uuid that will represent the code_challenge. When the auth method is called we get the base64 encoded challenge and also encrypt it with SHA256. If the login fails the code challege stays the same. When the user authenticates & afterwords logges out a new code challenge will be generated.

Code exchange flow

Code exchange with Nylas Identity works by detecting that the redirect url is present & also that eather the flow returned an error or the code it extracts the code challenge from storage and attempts the code exchange if successful it will set the JWT token and if it fails it will fire the onLoginFail() event.

API

All methods that are needed to interact with UAS authentication & sessions for client side apps.

auth

auth method is used to generate a link for an OAuth provider or in the case of hosted oauth enabled generate a link to UAS hosted login screen or is popup prop is set also open that link inside a popup window instead of returning a link

const link = await session.auth({
  Provider: "google",
});

Auth config

Auth config is used to configure the URL of the OAuth provider or Hosted url if hosted is enabled

Prop name	Type	Required	Description
provider	string	true	Nylas Client ID
scope	Array<string>	false	Scope overrides the default scope set in the Integration creation process
loginHint	string	false	Set the email that will be used to scope provider suggestions
includeGrantScopes	boolean	false	Used with loginHint to only ask for access of unauthorized provider scopes (Note: only used if loginHint provided)
metadata	object	false	Set additional metadata to be passed
settings	object	false	Set additional settings to be passed
hosted	boolean	false	Set if you want to use hosted page instead of your own implementation
prompt	string	false	Only applies if you are using Hosted auth
popup	boolean	false	Set if you want to open a popup instead of getting the link to the provider

authIMAP

Used to authenticate IMAP emails. On success returnes a redirect url when the user redirects to it the authentication is finished (code excahnge is done).

const link = await session.authIMAP({
  Provider: "google",
});

IMAP payload

Used to authenticate the user on the IMAP server specified in the payload. Note: Can only be used if you have an IMAP integration set, also the getAvailableProviders method returns IMAP providers with server configuration

Prop name	Type	Required	Description
imap_username	string	true	Email of IMAP account
imap_password	string	true	Password of the account
host	string	true	Host of IMAP server
port	int	true	Port of IMAP server
type	string	true	Type of IMAP provider (if the user provides IMAP server information set to generic)
smtp_host	string	true	Host of SMTP server
smtp_port	int	true	Host of SMTP server

IMAP responses

Successful response

{
  "success": true,
  "data": {
    "BaseURL": "http://localhost:3000?code=example_code"
  }
}

Failed response

{
  "success": false,
  "error": {
    "type": "invalid_authentication",
    "http_code": 400,
    "event_code": 25022,
    "message": "Authentication failed due to wrong input or credentials",
    "request_id": "dummy_request_id"
  }
}

isLoggedIn

Checks if the user is logged in (true/false).

const email = await session.isLoggedIn();

detectEmail

Used to detect a provider from the provided email address.

const email = await session.detectEmail("[e-mail]");

Response

Oauth detected

{
  "success": true,
  "data": {
    "provider": "google",
    "email_address": "[e-mail]",
    "detected": true
  }
}

IMAP detected

{
  "success": true,
  "data": {
    "provider": "imap",
    "type": "yahoo",
    "email_address": "[e-mail]",
    "detected": true
  }
}

No provider detected

{
  "success": true,
  "data": {
    "email_address": "[e-mail]",
    "detected": false
  }
}

Prop name	Type	Description
email_address	string	Email Address that was provided
detected	boolean	If the email has been paired with a provider
provider	string	Returns top level provider type (IMAP or an OAuth provider)
type	string	Returns IMAP type (provider)

applicationInfo

Returns information about application from the specified ClientID.

const email = await session.applicationInfo();

Response

{
  "data": {
    "application_id": "example_id",
    "name": "UAS App",
    "icon_url": "https://inbox-developer-resources.s3.amazonaws.com/icons/example"
  }
}

getAvailableProviders

Used to get OAuth & IMAP providers for the specified ClientID.

const providers = await session.getAvailableProviders();

Response

[
  {
    "name": "Google",
    "provider": "google",
    "type": "oauth",
    "settings": {}
  },
  {
    "name": "Yahoo",
    "provider": "yahoo",
    "type": "imap",
    "settings": {
      "name": "Yahoo",
      "imap_host": "imap.mail.yahoo.com",
      "imap_port": 993,
      "smtp_host": "smtp.mail.yahoo.com",
      "smtp_port": 587,
      "password_link": "https://help.yahoo.com/kb/learn-generate-password-sln15241.html",
      "primary": true
    }
  }
]

getProfile

If JWT present parses it and returns a profile object

const profile = await session.getProfile();

getScopes

If user is logged in returnes authenticated provider scopes

const scopes = await session.getScopes();

validateToken

Checks if the users token is valid when logged in (true/false)

const isValid = await session.validateToken();

logout

Destory the current session and loggout the user

await session.logout();

Events

Subscribe to events to get information about API interactions.

onLoginSuccess

Returns the response of code exchange

onLoginSuccess((event) => {
  console.log(event);
});

onLoginFail

Returns an error that happened during code exchange

onLoginFail((event) => {
  console.log(event);
});

onLogoutSuccess

Returns the logged out user if needed for re-auth

onLogoutSuccess((event) => {
  console.log(event);
});

onTokenRefreshSuccess

Returns the response of token exchange

onTokenRefreshSuccess((event) => {
  console.log(event);
});

onTokenRefreshFail

Returns an error that happened during token exchange

onTokenRefreshFail((event) => {
  console.log(event);
});

onSessionExpired

Returns the expired id token

onSessionExpired((event) => {
  console.log(event);
});