Skip to content

README.md

Latest commit

 

History

History
399 lines (224 loc) · 7.12 KB

README.md

File metadata and controls

399 lines (224 loc) · 7.12 KB
Raw

Interfaces

Functions

UserContextProvider

▸ UserContextProvider(__namedParameters): JSX.Element

This library implements the Authorization Code Grant Flow with PKCE.

import { UserContextProvider } from '@emdgroup/react-auth';
function App(): JSX.Element {
  return (
    <UserContextProvider autoLogin clientId="...">
      <Content />
    </UserContextProvider>
  );
}

function Content(): JSX.Element {
  const { info } = useUser();
  return <p>{info.email}</p>;
}

Parameters

Name Type
__namedParameters ProviderOptions

Returns

JSX.Element

getAccessToken

▸ getAccessToken(__namedParameters): Promise<string>

Return a valid access token for the current user. If the stored session is expired and a refresh token is available, the function attempts to refresh the session automatically. If the user is not authenticated, it rejects with an error. On refresh failure, the stored session is cleared.

const token = await getAccessToken({
  idpHost: 'login.emddigital.com',
  clientId: 'my-client-id',
});
fetch('/api/resource', { headers: { Authorization: `Bearer ${token}` } });

Throws

Error when the user is not authenticated (no stored session).

Parameters

Name Type
__namedParameters Object
__namedParameters.clientId string
__namedParameters.idpHost string
__namedParameters.signal? AbortSignal

Returns

Promise<string>

Promise that resolves to a bearer access token string.

refreshSession

▸ refreshSession(__namedParameters): Promise<UserSession>

Exchange a refresh token for a new session using the OAuth 2.0 refresh_token grant.

This function deduplicates concurrent calls: multiple invocations while a refresh is in progress will share the same promise. On success, it updates localStorage with the new session and emits a storage event to synchronize other tabs/components.

const session = await refreshSession({
  idpHost: 'login.emddigital.com',
  clientId: 'my-client-id',
  refreshToken,
});
// session.accessToken, session.expires, ...

Parameters

Name Type
__namedParameters Object
__namedParameters.clientId string
__namedParameters.idpHost string
__namedParameters.refreshToken string
__namedParameters.signal? AbortSignal

Returns

Promise<UserSession>

Promise that resolves to the renewed UserSession.

useUser

▸ useUser(): UserContext

Returns the user context previously established with UserContextProvider.

const { info, session, login, logout, authHeader } = useUser();

useEffect(() => {
  if (!session) return; // user is not logged in
  fetch('/api/pet', { headers: authHeader }).then(...);
}, [session, authHeader]);

Returns

UserContext

UserContext

The user context object is returned by the useUser hook.

Properties

authHeader

• Optional authHeader: Object

Convenience header object containing the Authorization header value set to the access token.

Index signature

▪ [key: string]: string

info

• Optional info: UserInfo

Provides the UserInfo object if the user is authenticated.

login

• Optional login: (opts?: LoginOptions) => void

Type declaration

▸ (opts?): void

Function to initiate the login flow.

Parameters
Name Type
opts? LoginOptions
Returns

void

loginUrl

• Optional loginUrl: string

Set to the URL that the user is redirected to initiate the authorization flow. Useful when you need to start the login flow in a separate window or tab. Use in combination with login({ refresh: false }).

logout

• Optional logout: () => void

Type declaration

▸ (): void

Function to log the user out.

Returns

void

session

• Optional session: UserSession

Provides the UserSession object if the user is authenticated.

ProviderOptions

Properties

acrValues

• Optional acrValues: string

Request a type of multi-factor authentication. Currently, mfa is the only supported value.

additionalParameters

• Optional additionalParameters: string

Additional query parameters, such as state=xyz.

autoLogin

• Optional autoLogin: boolean

When enabled, the user will automatically be logged in when the page is loaded. Defaults to false.

clientId

• clientId: string

Client ID as provided by the IdP.

domainHint

• Optional domainHint: string

Domain name to directly forward a user to the login page for a certain auth domain.

idpHost

• Optional idpHost: string

Overwrite the IdP host, defaults to login.emddigital.com.

prompt

• Optional prompt: "login"

Whether the authorization server prompts the user for re-authentication.

redirectUri

• Optional redirectUri: string

Overwrite the redirect URI, defaults to the current hostname + /auth.

refreshSession

• Optional refreshSession: boolean

Persist and use the refreshToken to renew an expired accessToken. Defaults to false.

userInfoEndpoint

• Optional userInfoEndpoint: string

Overwrite the userinfo endpoint, defaults to /oauth2/userinfo.

LoginOptions

Object representing the options for the login function of the UserContext.

Properties

entrypoint

• Optional entrypoint: string

Entrypoint to redirect the user to after successful authentication. Defaults to the URL that the user initially visited.

redirect

• Optional redirect: boolean

Automatically redirect the user to the login URL and to the entrypoint after successful authentication. Disabling this will disable all redirects. Defaults to false.

UserSession

Object containing the OIDC tokens and expiration time.

Properties

accessToken

• accessToken: string

OAuth access token provided by the IDP

expires

• expires: number

Epoch time in seconds when the access token expires

idToken

• Optional idToken: string

OAuth ID token provided by the IDP

refreshToken

• Optional refreshToken: string

OAuth refresh token provided by the IDP

UserInfo

Object representing the user details as provided by the IdP userInfo endpoint.

Hierarchy

  • Record<string, unknown>

    ↳ UserInfo

Properties

email

• email: string

Email address

familyName

• Optional familyName: string

Family name of provided

givenName

• Optional givenName: string

Given name of provided

sub

• sub: string

Subject identifier