How to authenticate

Authenticating Users

With Oolio Central SDK devlopers can implement login flows in their applications.

The following flows are currently supported for non-server applications.

1. OAuth2 PKCE Flow

   1. SPA/Mobile

   2. Servers

2. OAuth2 Device Code Flow

PKCE Flow

Use the PKCE Web login flow to show users login prompt and authorize the application. This flow is useful for any client side rendered web application or mobile application.

    sequenceDiagram
    autonumber
    participant User
    participant App
    participant STS as Oolio OIDC
    participant API as Your API

    User->>App: Click login link.
    App->App: Generate code verifier and code challenge
    App->>STS: Authorization code request + code challenge to /authorize
    STS-->>User: Redirect to login/authorization prompt.
    User->>STS: Authenticate and consent
    STS-->>App: Authorization code
    App->>STS: Authorization code + Code verifier to /oauth/token.

    STS->STS: Validate code verifier and challenge.

    STS-->>App: ID token and access token.
    App->>+API: Request user data with access token
    API-->>-App: Response

### Configuration

To get started, you would need to acquire client id for your application from Oolio developer portal.

Your application's redirect url must be registered for the provided client.

const issuer = new URL("https://auth.oolio.dev");
const clientId = "<application-client-id>"; // Get it from developer portal
const redirectUrl = "http://localhost:5173/callback"; // Change this for your application

const auth = new AppAuth({ issuer, clientId, redirectUrl }, sessionStorage);

You can use a different storage provider instead of [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)

</Tabs.Tab>

Navigate to login page

After initializing the client, start the login flow by calling

signinRedirect

. This will take the user to Oolio login page.

You muse handle the redirection yourself for your app.

<Tabs items={['TypeScript']}> <Tabs.Tab> In this example we are using

window.location

to navigate the user to login page.
Alternatively use other means to redirect. For example: use redirect or navigator.navigage() from react-router

```ts
const url = await auth.signinRedirect();
window.location.href = url; // change this based on your application
```

</Tabs.Tab>

Handle Callback

Once the user fills the login form and authorizes your app, the user will be navigated back to your application's provided

redirectUrl

with an authorization code.

Now we can exchange this authorization code for

access_token

and user information.

<Tabs items={['TypeScript']}> <Tabs.Tab> ```ts const url = new URL(window.location.href); // current URL const result = auth.completeRedirect(url);

console.log(result.access_token, result.user);
```

</Tabs.Tab>

Device Code Flow

    sequenceDiagram
    autonumber
    participant User
    participant App as Device App
    participant STS as Oolio OIDC
    participant API as Your API

    User->>App: Start App
    App->>STS: Authorization request to /oauth/device/code
    STS-->>App: Device Code + User Code + Verification URL
    App-->>User: User Code + Verification URL

    loop poll
        App->>STS: Poll for Access Token at /oauth/token
    end
    loop verify
      STS->>STS: Determine whether user has authorized device
    end

    par browser flow
        User->>STS: Go to Verification URL + enter User Code
        STS-->>User: Redirect to login/authorization prompt
        User->STS: Authenticate and Consent
        STS->>STS: Mark Device as Authorized
    end

    STS-->>App: Access Token
    App->>+API: Request user data with Access Token
    API-->>-App: Response

### Configuration

To get started, you would need to acquire client id for your application from Oolio developer portal.

import { AppAuth } from '@oolio-group/sso-sdk';

const issuer = new URL("https://auth.oolio.dev");
const clientId = "<application-client-id>"; // Get it from developer portal

const auth = new AppAuth({ issuer, clientId }, sessionStorage);

You can use a different storage provider instead of [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)

Generate Code

After initializing the client, start the login flow by calling

getDeviceCode

. This will generate new device code, user code, and provide a URL for users to enter the code and login.

You must handle showing user_code and verification_uri to the User.

Store

device_code

from the response for obtaining

access_token

later in step 4.

let deviceCode;

const code = await auth.getDeviceCode();
console.table(code.user_code, code.verification_uri);

// code.device_code must be stored in memory
deviceCode = code.device_code;

Show Code; Wait for User to Login

Show

user_code

and

verification_uri
You may show a QR code image for user's to login easily.

Users must now enter the code in the verification page, and authorize the app.

Verify Code; Obtain Token

Once the User completes the authorization prompt, we will be able to obtain

access_token

and user information.

<Tabs items={['TypeScript']}> <Tabs.Tab> ```ts // deviceCode is obtained in step 2 const result = await auth.verifyDeviceCode(deviceCode);

// token and user information can now be used in the app
console.table(result.access_token, result.user);
```

</Tabs.Tab>