@nylas/identity
TypeScript icon, indicating that this package has built-in type declarations

2.0.0-canary.2 • Public • Published

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

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("test@nylas.com");

Response

Oauth detected

{
  "success": true,
  "data": {
    "provider": "google",
    "email_address": "john@nylas.com",
    "detected": true
  }
}

IMAP detected

{
  "success": true,
  "data": {
    "provider": "imap",
    "type": "yahoo",
    "email_address": "john@yahoo.com",
    "detected": true
  }
}

No provider detected

{
  "success": true,
  "data": {
    "email_address": "john@asdad.com",
    "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);
});

Readme

Keywords

none

Package Sidebar

Install

npm i @nylas/identity

Weekly Downloads

765

Version

2.0.0-canary.2

License

MIT

Unpacked Size

149 kB

Total Files

36

Last publish

Collaborators

  • b3ndoi
  • krisgardiner
  • nylas-admin
  • poojaguggari
  • sourcesoft
  • ozsivanov
  • mrashed-dev