http://github.com/org/folio/mod-auth/login_module
This module provides a username/password based login mechanism for FOLIO credentials
Get login attempts for a single user
GET /authn/loginAttempts/{id}
Deprecated. Please use login-with-expiry instead. Will be removed in a future release. Get a new login token without an expiration (legacy endpoint)
POST /authn/login
Media type: application/json
Type: json
Content:
{
"title": "Login Credentials Schema",
"type": "object",
"description": "An entity that describes the basic credentials for a user to log on to the system",
"properties": {
"username": {
"description": "Username in the system, case insensitive",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
},
"tenant": {
"description": "Tenant; parameter for resolving duplicated usernames across tenants.",
"type": "string"
}
}
}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Object returned on successful login",
"type": "object",
"properties": {
"okapiToken": {
"description": "session token (X-Okapi-Token format)",
"type": "string"
},
"refreshToken": {
"description": "refresh token",
"type": "string"
}
},
"required": [
"okapiToken"
]
}
Bad request
Media type: text/plain
Type: any
Example:
Bad request
Not found
Media type: text/plain
Type: any
Example:
Not found
Unprocessable Entity
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Get an expiring refresh and access token
POST /authn/login-with-expiry
Media type: application/json
Type: json
Content:
{
"title": "Login Credentials Schema",
"type": "object",
"description": "An entity that describes the basic credentials for a user to log on to the system",
"properties": {
"username": {
"description": "Username in the system, case insensitive",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
},
"tenant": {
"description": "Tenant; parameter for resolving duplicated usernames across tenants.",
"type": "string"
}
}
}
access token cookie and refresh token cookie
Example:
Set-Cookie: folioAccessToken=abc.def.ghi; Max-Age=600; Expires=Tue, 23 Jan 2024 15:15:49 GMT; Path=/; Secure; HTTPOnly; SameSite=Strict
Set-Cookie: folioRefreshToken=rst.uvw.xyz; Max-Age=604800; Expires=Tue, 30 Jan 2024 15:05:49 GMT; Path=/authn; Secure; HTTPOnly; SameSite=Strict
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Object returned on successful login or on token refresh",
"type": "object",
"properties": {
"accessTokenExpiration": {
"description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
"type": "string"
},
"refreshTokenExpiration": {
"description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
"type": "string"
}
},
"required": [
"accessTokenExpiration",
"refreshTokenExpiration"
]
}
Bad request
Media type: text/plain
Type: any
Example:
Bad request
Not found
Media type: text/plain
Type: any
Example:
Not found
Unprocessable Entity
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Get a new refresh and access token
POST /authn/refresh
The Cookie header that must contain the refresh token cookie; all other cookies like the access token cookie are ignored
Example:
Cookie: folioRefreshToken=rst.uvw.xyz; folioAccessToken=abc.def.ghi
access token cookie and refresh token cookie
Example:
Set-Cookie: folioAccessToken=abc.def.ghi; Max-Age=600; Expires=Tue, 23 Jan 2024 15:15:49 GMT; Path=/; Secure; HTTPOnly; SameSite=Strict
Set-Cookie: folioRefreshToken=rst.uvw.xyz; Max-Age=604800; Expires=Tue, 30 Jan 2024 15:05:49 GMT; Path=/authn; Secure; HTTPOnly; SameSite=Strict
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Object returned on successful login or on token refresh",
"type": "object",
"properties": {
"accessTokenExpiration": {
"description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
"type": "string"
},
"refreshTokenExpiration": {
"description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
"type": "string"
}
},
"required": [
"accessTokenExpiration",
"refreshTokenExpiration"
]
}
Bad request
Media type: application/json
Type: any
Example:
Bad request
Unprocessable entity. mod-authtoken has returned a 400 level response.
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Logs the user out on their current device. The access token cookie and the refresh token cookie are removed, and the refresh token is invalidated. The access token cannot be invalidated and remains valid until its exiration time; this is by design because the access token is stateless.
POST /authn/logout
The Cookie header that must contain the refresh token cookie; all other cookies like the access token cookie are ignored
Example:
Cookie: folioRefreshToken=rst.uvw.xyz; folioAccessToken=abc.def.ghi
Bad request
Media type: application/json
Type: any
Example:
Bad request
Unprocessable entity. mod-authtoken has returned a 400 level response.
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Logs the user out on all of their devices
POST /authn/logout-all
Bad request
Media type: application/json
Type: any
Example:
Bad request
Unprocessable entity. mod-authtoken has returned a 400 level response.
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Self-update existing credentials. N.B. A non-empty password must be provided.
POST /authn/update
Media type: application/json
Type: json
Content:
{
"title": "Update Credentials Schema",
"type": "object",
"description": "An entity that describes the necessary data to update a user password",
"properties": {
"username": {
"description": "username",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "The current password of the user who will be replaced by the new one",
"type": "string"
},
"newPassword": {
"description": "New user password",
"type": "string"
}
}
}
Successful update
Bad request
Media type: text/plain
Type: any
Example:
Bad request
Unauthorized
Media type: text/plain
Type: any
Example:
Unauthorized
Unprocessable Entity
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Add a new login to the system. N.B. A non-empty password must be provided.
POST /authn/credentials
Media type: application/json
Type: json
Content:
{
"title": "Login Credentials Schema",
"type": "object",
"description": "An entity that describes the basic credentials for a user to log on to the system",
"properties": {
"username": {
"description": "Username in the system, case insensitive",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
},
"tenant": {
"description": "Tenant; parameter for resolving duplicated usernames across tenants.",
"type": "string"
}
}
}
Success
Bad request
Media type: text/plain
Type: any
Example:
Bad request
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Remove a user's login credentials from the system
DELETE /authn/credentials
User Id
Success
User not found
Media type: text/plain
Type: any
Example:
User not found
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Validate if password has been used before.
POST /authn/password/repeatable
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Object with password property",
"type": "object",
"properties": {
"password": {
"type": "string",
"description": "Password"
},
"userId": {
"type": "string",
"description": "User Id"
}
},
"required": [
"password",
"userId"
]
}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "result",
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "'invalid' if the password is in the user's password history, 'valid' otherwise"
}
},
"required": [
"result"
]
}
Example:
{
"result": "invalid"
}
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Resets password for user in record and deletes action record
POST /authn/reset-password
Media type: application/json
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Response entity to reset the password",
"type": "object",
"properties": {
"isNewPassword": {
"description": "true if a password has been set the first time for this user, false if the previous password has been moved into the user's password history",
"type": "boolean"
}
},
"additionalProperties": false
}
Media type: text/plain
Type: any
Example:
Bad Request
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Saves action to storage
POST /authn/password-reset-action
Media type: application/json
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Response entity to create a new password change action",
"type": "object",
"properties": {
"passwordExists": {
"description": "true if a password is stored for the user, false if no password (or even no credential entry) is stored for the user",
"type": "boolean"
}
},
"additionalProperties": false
}
Media type: text/plain
Type: any
Example:
Bad Request
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Retrieves action record by id
GET /authn/password-reset-action/{actionId}
Returns a list of events retrieved from storage
GET /authn/log/events
The maximum number of results to return.
Example:
10
The starting index in a list of results (starts at one).
A query string to filter users based on matching criteria in fields.
Saves received event into the storage
POST /authn/log/events
Removes events by filter
DELETE /authn/log/events/{id}
Returns single property 'credentialsExist' with true, if user has local password
GET /authn/credentials-existence