External Login - API

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.

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 customised.

Implement 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 calls your API from the IP address 57.128.60.142.
The outgoing IP address can be changed and more can be added over time.

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.

It is possible to configure additional parameters which is included in the JSON message.

This is a request JSON body for the username type email:

{
    "usernameType": 100,
    "username": "user1@somewhere.org",
    "password": "testpass1"
}

And this is a request 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": "user2@somewhere.org"
        },
        {
            "type": "role",
            "value": "some_access"
        }
    ]
}

Error
The API must return HTTP code 401 (Unauthorized) and an error (required) if the Basic authentication is rejected. Optionally add an error description in errorDescription.

{
    "error": "invalid_api_id_secret",
    "errorDescription": "Invalid API ID or secret"
}

The API must return HTTP code 400, 401 or 403 and an error (required) if the username and password combination is rejected. Optionally add an error description in errorDescription.

{
    "error": "invalid_username_password",
    "errorDescription": "Invalid username or password."
}

If other errors occur, the API should return HTTP code 500 or another appropriate error code. It is recommended to add a technical error message in to the return body. The error message can then later be found in the FoxIDs logs.

Error messages returned from the API is NOT displayed for the user only logged.

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 an external login authentication method to call your API in FoxIDs Control Client.

1. Navigate to the Authentication 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 customised the login UI.