SCRAM Authentication

SCRAM Authentication is performed using two requests made to /account/scramfirst and /account/scramfinal.

For a working example script performing SCRAM authentication see: https://bitbucket.org/softwareidm/mimtest/src/master/scripts/ScramAuth.ps1

For information about the SCRAM-SHA algorithm see RFC 5802

Any session authenticated to Identity Panel using SCRAM-SHA is automatically in the Writer role. logins must be manually initiated by an Identity Panel admin.

NOTE: Because SCRAM is normally a SASL mechanism, it has to be adapted to provide authentication at the HTTP application layer. This is accomplished by implementing the algorithm in normal HTTP POST MVC actions and embedding the protocol messages in a JSON wrapper.

Creating Credential

To create a credential a user with the Identity Panel Admin or Writer role must POST to /api/tenant/scramregister. This endpoint requires an application/json or application/bson payload with the structure:

{
  User: "username",
  Server: "servername",
  Alg: "SHA512|SHA256|SHA1" // optional, SHA512 is default
}

The controller action will infer the tenant from the accessing user's login context and generate a user id in the form: tenantid|servername|username. Requests attempting to authenticate as the user must match (non case-sensitive) on the entire generated user name including the tenant id uuid.

Panel Service/Panel Tool will automatically generate a username in this format using the login context of the service account or user running Panel Tool, the IP hostname properties of the server, and the tenant ID found in config.json.

If the registration request is authorized and successful, the returned response will be:

{
  Password: "random generated plaintext password"
}

Invoking Registration:

Registration may be invoked interactively by logging into Identity Panel and going to Settings / Install Service. Alternatively it may be invoked directly using an API call. This may be required if a user name is desired in a different form than domain\username as produced by Panel Service.

Authentication

SCRAM authentication uses two requests. The server must maintain state between requests to validate the work factor. In Identity Panel this state is persisted to the shared database as the tenant identification of the username is not trusted prior to authentication. Saving state to the database allows the web application to be stateless and not require session pinning. Only data needed to validate the second request is saved. Auth state is purged after 240 seconds meaning that initial and final scram requests must be made within 4 minutes.

Note: like other requests the API Key for the tenant must be passed in the X-API-Key header.

Since SCRAM provides mutual authentication, the client should validate the server after the final message.

Initial Request

For details on request payload see scram algorithm or sample script.

{
  Algorithm: "SHA512|SHA256|SHA1", // must match what was used to generate the user
  Message: "client first message"
}

Response

{
  Response: "server first message"
}

or

{
  Error: "error message"
}

NOTE: The following error messages will be returned with a 200 response code.

• Login failed, invalid username format
• Login failed, tenant not found
• Login failed, expired API Key
• Login failed, invalid API Key
• Login failed

Final Request

For details on request payload see scram algorithm or sample script.

{
  Algorithm: "SHA512|SHA256|SHA1", // must match what was used to generate the user
  Message: "client final message"
}

Response

{
  Response: "server final message"
}

// with login cookie for subsequent API calls

or

{
  Error: "error message"
}

NOTE: The following error messages will be returned with a 200 response code.

• Login failed, invalid username format
• Login failed, tenant not found
• Login failed