> For the complete documentation index, see [llms.txt](https://gsfcorp.gitbook.io/macula/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gsfcorp.gitbook.io/macula/administration-guide-v1.33.0/third-party-authentication-providers.md).

# Third Party Authentication Providers

Macula servers can use external authorization frameworks, such as OAuth, to facilitate user login, allowing your engineers and operators to use their existing accounts to log into Macula servers.

Currently supported authentication means:

* Google account
* Apple ID
* Microsoft account
* Okta
* custom (generic)

You can use public OAuth providers or, if your organization requires so, set up a local custom OAuth service.

{% hint style="info" %}
For public OAuth services to work: please reconfigure your system firewall(s) to allow browsers to connect to connect.vmsregistrationportal.com:5001 (allow HTTPS traffic to that port).
{% endhint %}

To set up user login with external authorization, follow these steps:

1. Add authentication provider(s) of your choice
2. Add user account
3. Activate the user account
4. Log in routinely
5. Repeat steps 2-4 for other users

Below, you will find a detailed description of each step.

#### Add a New Authentication Provider

In Macula Console, go to Configuration > Servers > double-click your server (Macula Global server if you are using Macula Enterprise system) > choose the Authentication providers tab. Click the Set up authentication providers button to open the existing provider list.

Choose your desired authentication service from the drop-down list in the bottom part of the window: for example, New OAuth provider (Google) if you wish to use Google accounts.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FwNZRD8gQvUdmr8hHYtnB%2Fimage.png?alt=media&amp;token=b4fe9bf0-682b-45ec-afe1-c9d941c3094c" alt=""><figcaption></figcaption></figure>

For each authentication provider, different settings are available. For Google, Microsoft, and Apple accounts, the settings are as follows:

| Setting               | Description                                                                                                                        | Default Value       |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Title                 | User-defined provider name that will be shown                                                                                      | Google              |
| Enable                | Enable or disable current authentication provider (use this option to temporarily disable the provider if you do not to remove it) | Enabled             |
| Provider type         | \[Automatic field]                                                                                                                 | \[Automatic field]  |
| Token expiration time | Time interval, during which the user will not have to enter their password again (session length)                                  | 7 days (7d00:00:00) |

The token expiration time defines how frequently the users will have to log in again. You may want to set the session expiration time equal to the operators' shift.

{% hint style="info" %}
For Okta and other (generic) authentication types you must provide additional settings and fill in all the suggested fields. You can retrieve these from the administrator who configured the authentication server.
{% endhint %}

Click OK to Save the newly created provider, then OK again to close the server settings dialog box.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FbVJz2dAVr2qsW4LZ12GV%2Fimage.png?alt=media&amp;token=07de6457-0ba5-49cc-8203-9d14dee80d9a" alt=""><figcaption></figcaption></figure>

#### Add Users

In Macula Console, go to the Configuration section and choose Users on the left. Click the drop-down arrow next to the *New user* button and choose New OAuth 2.0 user. It is a special user type for external authorization, which is first created in Macula Console and then activated after the user logs in for the first time, thus binding the internal user to the external authentication means.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2Fe6kkS1knPUTMbIJND0tz%2Fimage.png?alt=media&amp;token=5be9b14a-8039-4e14-8faa-e859b13449f6" alt=""><figcaption></figcaption></figure>

Checklist:

1. In the login field, enter the target user's **full login,** which they would normally enter into Google to log in. If the domain name is different from gmail, make sure to specify the full email address.
2. Grant the user the necessary **permissions**.
3. Save the settings, then copy the security **token** and send it to the user - they will need it when they log in for the first time.

After the user logs in, the account entry in Macula will become bound to the external authentication provider, and the security token here will be replaced with security ID. The user's name and full email address will be filled in automatically.

The rest of the settings are similar to the regular user settings.

#### Login

Users can now log into Macula servers using OAuth via both Macula Console and Macula Monitor. In either case, it is necessary to choose OAuth as login method.

When logging in for the very first time, they will have to enter the user token from Macula Console to bind the accounts. Provide them with the token to ensure they can use the OAuth login method.