@dstny/authenticator

This library provides way to authenticate agains a Dstny identity.

Initialization

The authenticator depends on an Authentication API and a Secure Storage.

Secure Storage: On Web platform you must use WebLocalStorage provided by @dstny/scp-storage package.
Authentication API: There are 2 supported implementations:

• SmgAuthApi used to authenticate against the SMG API
• OAuthApi used to authenticate directly against the Keycloak API

import Authenticator, { SmgAuthApi, AuthenticatorEvents } from '@dstny/scp-authenticator'
import { WebLocalStorage } from '@dstny/scp-storage'

const api = new SmgAuthApi(
  'https://api.development.aws.d4sp.com/api-user', // base url
  'syslab', // realm
  'connect-me' // client-id
)
const secureStorage = new WebLocalStorage()

const authenticator = new Authenticator(api, secureStorage)

Once the authenticator is instantiated we must intialize it.

await authenticator.setup()

Login

If a valid access token or refresh token was found in storage during the setup, the user will be authenticated automatically. authenticator.credentials is defined when the user is authenticated. This variable will be set (or not) after await authenticator.setup() is invoked. Events will also be emitted to notify when the user is authenticated.

If the user is not authenticated in automatically, the first thing to do, is to check if a code is present in the url, when that is the case, you should extract it and use it to signIn

const query = new URLSearchParams(window.location.search)
const code = query.get('code')

await authenticator.signIn(code, redirectUri) // events will be emitted

window.history.replaceState({}, document.title, window.location.pathname) // remove 'code' parameter from url once it was used

When the user is not logged in, and no code is present in the url, you can login the user, to do this you need to obtain the login url, and redirect the browser to it.

const redirectUri = window.location.origin // this is only an example, you might have a different redirect uri

const url = await authenticator.getLoginUrl(redirectUri)
window.location.href = url

Logout

To logout use signOut. Events will be emitted with undefined value to notify that no user is currently authenticated.

await authenticator.signOut() // events will be emitted

Destroy

Once the authenticator is no longer required it can be destroyed.

await authenticator.destroy()

This will not logout the user from Keycloak.

Events

The library provides set of events which will be invoked when the state changes or when value of the credentials, access token and jwt payload changes.

For all the events below you can assume that:

• if the previous value was falsy then became truthy, the user logged in
• if the previous value was truthy then became falsy, the user logged out
• if the previous value was truthy and stayed truthy, the tokens were refreshed and new values are available.

authenticator.on(AuthenticatorEvents.STATE_CHANGE, (state) => {
  if (state) {
    // user is authenticated
  } else {
    // user is not authenticated
  }
})

authenticator.on(AuthenticatorEvents.CREDENTIALS, (credentials) => {
  if (credentials) {
    // user is authenticated, credentials object contains
    // the access token, the refresh token and the expiry time
  } else {
    // user is not authenticated
  }
})

authenticator.on(AuthenticatorEvents.ACCESS_TOKEN, (accessToken) => {
  if (accessToken) {
    // user is authenticated, accessToken contains the
    // the access token string
  } else {
    // user is not authenticated
  }
})

authenticator.on(AuthenticatorEvents.JWT_PAYLOAD, (jwt) => {
  if (jwt) {
    // user is authenticated, jwt object contains
    // the decoded payload from the access token
  } else {
    // user is not authenticated
  }
})

Authentication API & Coven

Coven will provide the Authentication API configuration. Coven will replace specific strings placed in the files with configuration.

__COVEN_SDK_LOGIN_METHOD__ indicates which Authentication API implementation you must use, when:

• smg you are expected use use SmgAuthApi implementation,
• otherwise you must use OAuthApi implementation.

SmgAuthAPI

class SmgAuthApi extends AbstractAuthenticationApi {
  constructor(baseURL: string, realm: string, clientId: string)
}

| String | Contains | Example | | ----------------------------- | ---------- | ----------------------------------------------- | | __COVEN_SDK_SMG_AUTH_URL__ | baseURL | https://api.development.aws.d4sp.com/api-user | | __COVEN_SDK_SMG_CLIENT_ID__ | clientId | connect-me | | __CONNECTME_SDK_SMG_REALM__ | realm | syslab1 |

OAuthApi

class OAuthApi extends AbstractAuthenticationApi {
  constructor(baseURL: string, clientId: string, authorizationRoute: string, scope: string)
}

| String | Contains | Example | | ----------------------------------------- | -------------------- | ----------------------------------------------------------------------------- | | __COVEN_SDK_OAUTH_URL__ | baseURL | https://keycloak.test.aws.d4sp.com/auth/realms/odos/protocol/openid-connect | | __COVEN_SDK_OAUTH_CLIENT_ID__ | clientId | connect-me | | __COVEN_SDK_OAUTH_AUTHORIZATION_ROUTE__ | authorizationRoute | /auth | | __COVEN_SDK_OAUTH_SCOPE__ | scope | |

Example

An example application can be found in the example directory.