Introduction

UAS login component is used to simplify the flow of authentication for OAuth and IMAP providers

by using the nylas-identity package so that the end user does not have to implement it.

Login component configuration & Concepts

| Prop name | Type | Required | Description | Possible Values | | --------------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | clientId | string | TRUE | Nylas Public Application ID | Nylas app/client id | | redirectUri | string | TRUE | Redirect URI of type js | One of Nylas app allowed redirectUris | | config | object | FALSE | Additional settings for OAuth control & UAS domain configuration | see table below | | hosted | boolean | FALSE | If used will redirect to our hosted login component. Note all other fields will be reflected after redirect | | | providers | string comma separated | FALSE | List of providers displayed in the initial login screen, separated by , and displayed in the order of writing them. Note: if providers specified are not created inside the application the default logic will be used | google, microsoft, yahoo, imap, icloud, aol, verizon, outlook (order matters) | | prompt | string comma separated | FALSE | Prompt represents the types of login methods available to the user upon rendering the component. It is provided as a string separated by , and displayed in the order of writing them | detect, select_provider (order matters) | | popup | boolean | FALSE | If used will open a new popup window for the selected provider. Node: If used in combination with the Hosted param it will open hosted auth page inside the popup | | | loginHint | string | FALSE | If provided will inject the email in all types of auth flows that are available for that application | |

config object

| Prop name | Type | Required | Description | Possible Values | | ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | domain | string | FALSE | Specify the domain of UAS if client has dedicated url (currently defaults to localhost:3030 for local development (will be updated to MT prod URL by default) | | | authSettings | object | FALSE | Additional settings for more control over the login component behavior | see table below | | hostedSettings | object | FALSE | Hosted settings only used by hosted login component for server side rendering. Will not be documented for the end user.. | |

authSettings object

| Prop name | Type | Required | Description | Possible Values | | ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | scopes | object | FALSE | Overrides the default scopes inside integrations. Key is the provider name ex:google and value is an array of scopes Note: does not apply to IMAP | { ”google”:”….”} | | state | string | FALSE | Passes state through the OAuth flow | “test_id” | | includeGrantScopes | boolean | FALSE | Used only with loginHint | true |

Default providers functionality

Providers are displayed based on the providers prop but if the prop is not specified the order of providers displayed in the select_providers prompt goes like this:

• if the user has providers that are of type OAuth they are displayed first and in an alphabetical order
• If there is an IMAP integration the providers of IMAP are displayed first (still OAuth integrations come first in total order of things) by priority and then alphabetical order.
• Additionally if there is an OAuth provider that also exists as an IMAP provider (eg Yahoo supports both OAuth and IMAP), we remove that IMAP provider and enforce the use of OAuth for those emails (ex. Microsoft Outlook will be removed if a Microsoft integration exists )

List of primary IMAP providers:

• AOL Mail
• Gmail
• iCloud
• Microsoft Outlook
• Verizon
• Yahoo
• Yandex
• Above providers get promoted to the initial first page of provider list, and then comes other IMAP mappings we have in the list of all providers sub-page

Application info

All configuration provided (descriptive) for the specified clientId inside UAS like: app name, image… is set to the Login Component and fetched by nylas-identity library on the client side.

Hosted behavior

With hosted OAuth enabled in all the configuration for the embedded/react component is passed to the hosted screen and will take effect in the same way.

Note: this can be accomplished by only using the nylas-identity NPM package

Ex. If you set a provider list it will be the same on our UAS hosted as it would in the component inside there application

Popup behavior

Popup can be used to access provider OAuth pages or UAS hosted page inside a popup window and code exchange and all errors will be relayed back to the page that opened the popup.

Detect providers functionality (prompt: “detect”)

By providing an email address we can check our domain list and also MX records for the specified email and prompt the user to use a provider that can best handle the email address.

Note: Providers detected reflect users created integrations, if the user has IMAP integration and provides us with an email we do not have inside our list we prompt the user to enter the whole IMAP config by themselves. But if they provide an email that is not detected and they do not have IMAP enabled they will get an error saying we could not find a provider for the specified email address.

Logged in status

If the authentication was a success the login component is hidden. In customer’s application, the developer can access the login status by accessing the nylas-identity object (NylasSessions).

const loggedIn = await global.NylasSessions.isLoggedIn(); // boolean

Running login compoenent localy

StoryBook

• Inside of your projects folder add nylas-identity by cloning it git clone https://github.com/nylas/nylas-identity.git & install npm packages npm install
• Clone the nylas-component repo & install npm packages npm install
• Before running storybook you can add your base configuration (clientId, UAS domain & redorectUri) by runing the following command and editing the file cp .env_example .env
• Run npm run storybook to see the examples provided

Embed as a JS minified bundle

<link
  href="https://storage.googleapis.com/mt-statics-test/uas/hosted/css/nylas-component.css"
  rel="stylesheet"
/>
<script src="https://storage.googleapis.com/mt-statics-test/uas/hosted/js/nylas-component.js"></script>

Configuration

Minimum configuration

The minimum configuration will use the embedded (non-popup) version of login component and will use the default integration that is created for that application.

global.NylasComponent(
  {
    clientId: "71cz77z6osjenfgev3n1nxbq",
    redirectURI: "http://localhost:5502/",
  },
  "login-component",
);