External Login

With external login you can authenticate users in your existing user database with an API call. You implement the API which is called with a username and password, and the API then validate the username and password combination and return a response indicating success or failure.
You would use an external login authentication method if you have an existing user store to leverage the user store as a possible authentication method in FoxIDs. After login it is possible to create external users and optionally show a dialog where the user e.g., can put in a name, email etc.

If desired, you can possible over time migrate users to FoxIDs and phase out the API and existing user store. However, it requires that emails have been added to the users.

External login support two username types:

• Email - the user's email as the username
• Text - a text-based username

If you choose a text-based username, the username format is not validated in FoxIDs. With text-based username it is possible to combination different username formats, include using an email.

It is only possible to use home realm discovery (HRD) based on the domain if you select the email username type.

This is the default external login UI with a text-based username.

The external login UI can be customized.

API

You need to implement a simple API that FoxIDs calls on every authentication request.
Please have a look at the sample code.

The API has a base URL and the functionality is divided into folders. Currently, only the authentication folder (functionality) for validating the username and password is support.
Other folders for changing passwords and creating new users will be added later.

If the base URL for the API is https://somewhere.org/mystore the URL for the authentication folder will be https://somewhere.org/mystore/authentication.

FoxIDs cloud call the API from the IP address 57.128.60.142.

Request

The API call is secured with HTTP Basic authentication scheme where FoxIDs sends the ID external_login as the username and the configured secret as the password.

The API is called with HTTP POST and a JSON body.

This is a JSON body for the username type email:

{
    "usernameType": 100,
    "username": "[email protected]",
    "password": "testpass1"
}

And this is a JSON body for the username type text:

{
    "usernameType": 200,
    "username": "user1",
    "password": "testpass1"
}

The username types:

• email is 100
• text is 200

Response

Success
On success the API should return HTTP code 200 and optionally a list of claims for the authenticated user.

For example, the user's, sub (unique ID / username), name, email and maybe even a role:

{
    "claims": [
        {
            "type": "sub",
            "value": "somewhere/user2"
        },
        {
            "type": "given_name",
            "value": "Joe"
        },
        {
            "type": "family_name",
            "value": "Smith"
        },
        {
            "type": "email",
            "value": "[email protected]"
        },
        {
            "type": "role",
            "value": "some_access"
        }
    ]
}

Error
The API must return HTTP code 401 (Unauthorized) if the Basic authentication is rejected.

The API must return HTTP code 403 (Forbidden) if the username and password combination is rejected.

If other errors occur, the API should return HTTP code 400 (Bad Request), 500 (Internal Server Error) or another or another appropriate error code.

In all error cases, a technical error message should be added to the return body. The error message can then later be found in the FoxIDs logs.
The error message is NOT displayed for the user.

API Sample

The sample ExternalLoginApiSample show how to implement the API in ASP.NET Core 8.

You can user this Postman collection to call and test the sample with Postman.

Configure

Configure a external login authentication method to call your API in FoxIDs Control Client.

1. Navigate to the Authentication Methods tab
2. Click New authentication
3. Select Show advanced
4. Select External Login
5. Add the Name
6. Select Username type (in this case a text-based username)
7. Add the base API URL without the authentication folder in API URL
8. Add the API secret
9. Click Create

Optionally click Show advanced in the top right corner of the configuration section to customized the login UI.