Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(api-spec): last used, device trust, remember me #108

Merged
merged 3 commits into from
Dec 12, 2024
Merged

feat(api-spec): last used, device trust, remember me #108

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
646bfdd
feat(api-spec): update flow success payload with last login method data
lfleischmann Dec 2, 2024
4d67b62
feat(api-spec): add device trust info
lfleischmann Dec 5, 2024
6223706
feat(api-spec): add info about session retention header
lfleischmann Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 137 additions & 31 deletions openapi-flow.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,6 +515,23 @@ components:
action:
enum:
- "skip"
ActionTrustDevice:
description: |
Execution of this action indicates that a user considers the device or browser used as trusted. As a
result, MFA (if it is enabled and the user has registered an MFA credential) is skipped for subsequent logins.
Trust persists until it explicitly expires and its expiry is not
extended on subsequent logins. Users must provide MFA again after expiry.

Generates a random device token that is returned to the client in a `Set-Cookie` header on flow success.
The action is only present in the flow response if this Cookie is not set, i.e. if no trust has been granted
or if the cookie has expired.
allOf:
- $ref: "#/components/schemas/Action"
- type: object
properties:
action:
enum:
- "trust_device"
ActionVerifyPasscode:
description: Verify a passcode.
allOf:
Expand Down Expand Up @@ -602,6 +619,15 @@ components:
type: object
additionalProperties:
$ref: "#/components/schemas/Action"
ActionsDeviceTrust:
type: object
properties:
trust_device:
$ref: "#/components/schemas/ActionTrustDevice"
skip:
$ref: "#/components/schemas/ActionSkip"
back:
$ref: "#/components/schemas/ActionBack"
ActionsCredentialOnboardingChooser:
type: object
properties:
Expand Down Expand Up @@ -1595,16 +1621,16 @@ components:
$ref: "#/components/schemas/InputEmail"
username:
$ref: "#/components/schemas/InputUsername"
InputsSecurityKeyDelete:
type: object
properties:
security_key_id:
$ref: "#/components/schemas/InputSecurityKeyID"
InputsRegisterPassword:
type: object
properties:
new_password:
$ref: "#/components/schemas/InputNewPassword"
InputsSecurityKeyDelete:
type: object
properties:
security_key_id:
$ref: "#/components/schemas/InputSecurityKeyID"
InputsSessionDelete:
type: object
properties:
Expand Down Expand Up @@ -1670,6 +1696,27 @@ components:
properties:
email:
$ref: "#/components/schemas/InputUsername"
LastLogin:
description: Contains data about the last login and MFA methods used by the user.
type: object
properties:
login_method:
description: The login method used.
type: string
enum:
- password
- passkey
- passcode
- third_party
mfa_method:
description: The MFA method used.
type: string
enum:
- totp
- security_key
third_party_provider:
description: Contains the name of the third party provider used if `login_method` is `third_party`.
type: string
Link:
type: object
properties:
Expand Down Expand Up @@ -1824,6 +1871,18 @@ components:
$ref: "#/components/schemas/Link"
nullable: true
example: []
StateDeviceTrust:
title: DeviceTrust
allOf:
- $ref: "#/components/schemas/StateBase"
- type: object
properties:
actions:
$ref: "#/components/schemas/ActionsDeviceTrust"
name:
type: string
enum:
- "device_trust"
StateLoginInit:
title: LoginInit
allOf:
Expand Down Expand Up @@ -2399,13 +2458,24 @@ components:
- $ref: "#/components/schemas/StateMFASecurityKeyCreation"
- $ref: "#/components/schemas/StatePasscodeConfirmation"
- $ref: "#/components/schemas/StatePasswordCreation"
- $ref: "#/components/schemas/StateOnboardingEmail"
- $ref: "#/components/schemas/StateOnboardingUsername"
- $ref: "#/components/schemas/StateCredentialOnboardingChooser"
- $ref: "#/components/schemas/StateOnboardingCreatePasskey"
- $ref: "#/components/schemas/StateOnboardingVerifyPasskeyAttestation"
- $ref: "#/components/schemas/StateOnboardingEmail"
- $ref: "#/components/schemas/StateOnboardingUsername"
- $ref: "#/components/schemas/StateDeviceTrust"
- $ref: "#/components/schemas/StateThirdParty"
- $ref: "#/components/schemas/StateSuccess"
- allOf:
- $ref: "#/components/schemas/StateSuccess"
- type: object
properties:
payload:
allOf:
- $ref: "#/components/schemas/PayloadProfileData"
- type: object
properties:
last_login:
$ref: "#/components/schemas/LastLogin"
discriminator:
propertyName: name
mapping:
Expand All @@ -2422,11 +2492,12 @@ components:
mfa_method_chooser: "#/components/schemas/StateMFAMethodChooser"
mfa_otp_secret_creation: "#/components/schemas/StateMFAOTPSecretCreation"
mfa_security_key_creation: "#/components/schemas/StateMFASecurityKeyCreation"
onboarding_email: "#/components/schemas/StateOnboardingEmail"
onboarding_username: "#/components/schemas/StateOnboardingUsername"
credential_onboarding_chooser: "#/components/schemas/StateCredentialOnboardingChooser"
onboarding_create_passkey: "#/components/schemas/StateOnboardingCreatePasskey"
onboarding_verify_passkey_attestation: "#/components/schemas/StateOnboardingVerifyPasskeyAttestation"
onboarding_email: "#/components/schemas/StateOnboardingEmail"
onboarding_username: "#/components/schemas/StateOnboardingUsername"
device_trust: "#/components/schemas/StateDeviceTrust"
thirdparty: "#/components/schemas/StateThirdParty"
success: "#/components/schemas/StateSuccess"
StatesProfile:
Expand Down Expand Up @@ -2520,34 +2591,62 @@ components:
format: JWT
X-Session-Lifetime:
type: number
X-Session-Retention:
type: string
enum:
- persistent
CookieSession:
description: |
Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)

Only present on the `success` state of the flow.
type: string
example: hanko=<JWT>; Path=/; HttpOnly
CookieDeviceToken:
description: |
Issued on a login flow's success if the `trust_device` action was executed during the flow. Used during
subsequent login flows to check if MFA (if it is enabled and the user has registered an MFA credential)
can be skipped.

Only present on the `success` state of the flow.
type: string
example: |
hanko-device-token=dl4yEFrW8XYU2GQ6IN3gJeqTiVhDKsfK_GYh-_HsAk4ZBdG1M6iA6QXQDJGSJNruS41_-bHTnlDjx8GyJ_WKA==,Path=/; HttpOnly, Secure
responses:
LoginFlowResponse:
description: LoginFlowResponse
headers:
X-Auth-Token:
description: |
Used for cross-domain communication between client and Hanko API.

Only present if configured on the tenant and on the `success` state of the flow.
schema:
$ref: '#/components/schemas/X-Auth-Token'
X-Session-Lifetime:
description: |
Contains the seconds until the session expires.

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/X-Session-Lifetime'
Set-Cookie:
X-Session-Retention:
description: |
Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)
Serves as a hint at what type of cookie (session or persistent) should be created.

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/CookieSession'
$ref: '#/components/schemas/X-Session-Retention'
Set-Cookie:
schema:
anyOf:
- $ref: '#/components/schemas/CookieSession'
- $ref: '#/components/schemas/CookieDeviceToken'
examples:
session:
value: hanko=<JWT>; Path=/; HttpOnly
device_token:
value: hanko-device-token=dl4yEFrW8XYU2GQ6IN3gJeqTiVhDKsfK_GYh-_HsAk4ZBdG1M6iA6QXQDJGSJNruS41_-bHTnlDjx8GyJ_WKA==,Path=/; HttpOnly, Secure
content:
application/json:
schema:
Expand Down Expand Up @@ -2716,21 +2815,28 @@ components:
description: |
Enable via configuration option `session.enable_auth_token_header`
for purposes of cross-domain communication between client and Hanko API.

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/X-Auth-Token'
X-Session-Lifetime:
description: |
Contains the seconds until the session expires.

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/X-Session-Lifetime'
X-Session-Retention:
description: |
Serves as a hint at what type of cookie (session or persistent) should be created.

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/X-Session-Retention'
Set-Cookie:
description: |
Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)

Only present on the `success` state of the flow.
schema:
$ref: '#/components/schemas/CookieSession'
Expand Down Expand Up @@ -2787,19 +2893,19 @@ components:
properties:
input_data:
oneOf:
- $ref: "#/components/schemas/InputDataRegisterClientCapabilities"
- $ref: "#/components/schemas/InputDataContinueWithLoginIdentifier"
- $ref: "#/components/schemas/InputDataEmailAddressSet"
- $ref: "#/components/schemas/InputDataVerifyPasscode"
- $ref: "#/components/schemas/InputDataPasswordLogin"
- $ref: "#/components/schemas/InputDataRegisterPassword"
- $ref: "#/components/schemas/InputDataPasswordRecovery"
- $ref: "#/components/schemas/InputDataOTPCodeVerify"
- $ref: "#/components/schemas/InputDataOTPCodeValidate"
- $ref: "#/components/schemas/InputDataThirdPartyOauth"
- $ref: "#/components/schemas/InputDataExchangeToken"
- $ref: "#/components/schemas/InputDataWebauthnVerifyAttestationResponse"
- $ref: "#/components/schemas/InputDataWebauthnVerifyAssertionResponse"
- $ref: "#/components/schemas/InputDataRegisterClientCapabilities"
- $ref: "#/components/schemas/InputDataContinueWithLoginIdentifier"
- $ref: "#/components/schemas/InputDataEmailAddressSet"
- $ref: "#/components/schemas/InputDataVerifyPasscode"
- $ref: "#/components/schemas/InputDataPasswordLogin"
- $ref: "#/components/schemas/InputDataRegisterPassword"
- $ref: "#/components/schemas/InputDataPasswordRecovery"
- $ref: "#/components/schemas/InputDataOTPCodeVerify"
- $ref: "#/components/schemas/InputDataOTPCodeValidate"
- $ref: "#/components/schemas/InputDataThirdPartyOauth"
- $ref: "#/components/schemas/InputDataExchangeToken"
- $ref: "#/components/schemas/InputDataWebauthnVerifyAttestationResponse"
- $ref: "#/components/schemas/InputDataWebauthnVerifyAssertionResponse"
csrf_token:
$ref: "#/components/schemas/CSRFToken"
additionalProperties: false
Expand Down