Octopod Auth

Package for managed authentication to Octopod

1. Installation

Install the package with NPM :

yarn add @octo-produits-internes/octopod-auth

You must have react@18 installed as a peer requirement.

2. Getting started

Simply import the Authenticator context from the package and wrap it around the part of your code which needs authentication to Octopod :

import { Authenticator } from '@octo-produits-internes/octopod-auth'

export const MyComponent = ({ prop1, prop2 }) => (
  <div>
    <span>This part does not need authentication</span>
    <Authenticator.Provider>
      <MyComponentWithAuthentication />
    </Authenticator.Provider>
  </div>
)

Then, in your component, consume this context :

import { useAuthenticator } from '@octo-produits-internes/octopod-auth'

export const MyComponentWithAuthentication = ({ prop1, prop2 }) => {
  const { connection, login } = useAuthenticator()

  return (
    <div>
      <button onClick={login}>Click me to login !</button>
      {
        connection.status === 'authorized'
          ? <div>You are authenticated !</div>
          : <div>You are not yet authenticated.</div>
      }
    </div>
  )
}

When the login function is called, Authenticator.Provider will try to validate your stored refresh key if you have one, or redirect you to the Octopod authentication if you have none. Whenever the authentication flow is successful, the connection context value will describe the connection (see documentation below for all exposed values). You can then use the useOctopod hook to begin working with the Octopod API.

You can specify a host to login to :

• octopod-production will forward to https://octopod.octo.com
• octopod-test will forward to https://octopod-test.herokuapp.com (default)
• octopod-test-2 will forward to https://octopod-test-2.herokuapp.com

If you want all stored data to be cleaned and connection reset to the stale status, call the logout function.

Please note you will have to add the specified host to your server CSP in connect-src, and ask the Produits Internes team to authorize your domain on it. By default, http://localhost:8080 and https://localhost:8080 are authorized on both test instances.

3. Documentation

contexts/Authenticator

connection: Connection

Describes current connection to Octopod with the given keys :

• status is an enum which is equal to :
  • stale when no connection has been attempted
  • pending when the connection is awaiting for a response (default)
  • unauthorized when the connection exists and is unauthorized, or any error was thrown
  • authorized when the connection exists and is authorized
• tokens (only present when authorized is true) is object with the given keys:
  • access is the access token
  • refresh is the refresh token
• url (only present when authorized is true) is a string equal to the host on which the connection is authorized

errors: string[]

Contains all registered errors in the authentication process. Possible errors are :

• could not connect to Octopod if the Octopod server could not be reached (possibly Octopod authentication server is down)
• could not parse tokens from Octopod: body could not be parsed as JSON if the Octopod authentication server is up but responded with no parseable content.
• could not parse tokens from Octopod: at least the access or refresh key are missing if the Octopod authentication server is up, responded with parseable content but misses at least one of the two required keys.
• Any other exception will be included.

login: (host?: Host) => Promise

Parameters :

• host (optional) can be "octopod-production", "octopod-test" or "octopod-test-2"

Returns :

• an asynchronous promise the login attempt has finished

logout: () => Promise

Returns :

• an asynchronous promise the logout has finished

hooks/useOctopod

errors: string[]

Contains all registered request errors. Possible errors are :

• could not call the Octopod API without being authenticated if the Authenticator context is not authenticated

fetchFromOctopod: (method: OctopodHook.HTTPMethod, route: string, options?: OctopodHook.Options) => Object

Fetches data from the given Octopod API at the given route. Please refer to the Octopod API documentation about the exposed routes.

Parameters:

• method (required) must be "GET", "POST", "PUT", "PATCH" or "DELETE"
• route (required) must be any string
• options (all optional) must be an object with the given keys :
  • api must be "v0" or "v1"
  • body must be a string representing the request body
  • contentType must be a string representing a MIME type
  • parameters must be an object mapping all request parameters

Returns :

• the context is not authenticated => null
• the context is authenticated and the response has no body => {}
• the context is authenticated and the response has a body => the body parsed from JSON to an hash

4. Development

Clone this repository and install all dependencies with yarn install --check-files. Then, the following commands will be usable :

• yarn start:example: starts a headless server at localhost:8080 to show a use case example (defined in src/main.example.tsx),
• yarn start:example:ssl: same as yarn start:example but the server will serve over HTTPS, as long as you have both certs/octopod-auth.pem and certs/octopod-auth-key.pem
• yarn reinstall: reinstalls all dependencies in a clean state,
• yarn test: starts tests for the specified file if specified, all files if not
• yarn test:watch: same as yarn test, but will run in watch mode
• yarn test:output: same as yarn test, but will output the results in src/config/jest/jest.result.json
• yarn test:coverage: same as yarn test:output, but will output the coverage in the console and in src/config/jest/coverage/
• yarn test:coverage:inspect: same as yarn test:coverage, but will start a headless server at localhost:8081 to show coverage results
• lint: starts linting on the specified file
• lint:all: same as yarn lint, but lints on all files

5. License

All rights reserved to OCTO Technology (France). Credit goes to the Produits Internes team. Use for other businesses is strictly prohibited.