# Using authentication

If your wolkenkit application is using authentication, you must configure your client application accordingly. For that, provide the authentication property with an authentication strategy when connecting to an application.

# Using OpenID Connect

Currently, OpenID Connect is the only supported authentication strategy for web clients. Using this authentication strategy, you can integrate your application with various identity services such as Auth0.

To use OpenID Connect, create an instance of the wolkenkit.authentication.OpenIdConnect strategy and provide it using the authentication property:

wolkenkit.connect({
  host: 'local.wolkenkit.io',
  authentication: new wolkenkit.authentication.OpenIdConnect({
    identityProviderUrl: 'https://...',
    clientId: '...'
  })
}).
  then(app => /* ... */).
  catch(err => /* ... */);

# Configuring OpenID Connect

If you need to set the redirect URL dynamically, additionally provide a redirectUrl property. Please note that this only works if the given redirect URL is configured at your OpenID Connect identity provider.

Using the scope property you can get additional profile information on the user:

wolkenkit.connect({
  host: 'local.wolkenkit.io',
  authentication: new wolkenkit.authentication.OpenIdConnect({
    identityProviderUrl: 'https://...',
    clientId: '...',
    scope: 'profile'
  })
}).
  then(app => /* ... */).
  catch(err => /* ... */);

# Using Local

The Local authentication strategy is currently the only supported authentication strategy for services written in Node.js. Using this authentication strategy, you can issue your own tokens.

To use Local, create an instance of the wolkenkit.authentication.Local strategy and provide it using the authentication property. Additionally you must provide an identity provider name and a certificate as well as a private key in .pem format:

wolkenkit.connect({
  host: 'local.wolkenkit.io',
  authentication: new wolkenkit.authentication.Local({
    identityProviderName: 'https://...',
    certificate: '...',
    privateKey: '...'
  })
}).
  then(app => /* ... */).
  catch(err => /* ... */);

# Managing the authentication lifecycle

No matter which authentication strategy you use, the application provides an auth property that allows you to manage the authentication lifecycle.

To find out whether there is a currently logged in user, call the app.auth.isLoggedIn function:

if (app.auth.isLoggedIn()) {
  // ...
}

To login a user manually, call the app.auth.login function. How this works in detail depends on the configured authentication strategy. If you are using OpenID Connect, all you need to do is call the function:

app.auth.login();

If you are using the Local authentication strategy, you need to provide the sub claim as parameter:

app.auth.login('Jane Doe');

Additionally, you may specify custom claims that shall be included in the token:

app.auth.login('Jane Doe', {
  'https://.../roles': [ 'administrator' ]
});

To logout a user, call the app.auth.logout function:

app.auth.logout();

# Accessing the user profile

To get the user profile call the app.auth.getProfile function. The profile is then returned as an object that contains claims about the user. If there is no logged in user, the function returns undefined:

const profile = app.auth.getProfile();

Typically, you will find information such as first name, last name, or email in the profile, but its specific content depends on the authentication strategy and the identity provider being used. If in doubt, have a look at the profile object that is being returned.

# Accessing the low-level token

In rare cases you may need to access the raw low-level JWT token that is used by the wolkenkit SDK internally to authenticate the user against the wolkenkit application. To retrieve the token call the app.auth.getToken function:

const token = app.auth.getToken();