Endpoints and Base URLs#

An authentication profile uses a base URL and has multiple base endpoint paths. This guide summarizes how base URLs and endpoints work. Get to know paths by running some example authentication flows like those in the Getting Started Guides.

To view the endpoint details for the authentication profile, use the Admin UI and navigate to Authentication Service → Endpoints. The full endpoint URLs are formed by appending paths to the profile’s external base URL so that clients receive resolvable URLs in redirect responses.

Authenticator Endpoints
Authenticator Endpoints

Any backend HTTP endpoints that Custom Authenticators or Authentication Actions expose run at a child path under the base endpoints.

Endpoint Usage#

Applications trigger the use of authentication endpoints when they begin a flow, typically with a security protocol like OAuth or SAML. OAuth clients are registered against a token profile, whereas SAML clients (service providers) are registered against a SAML IDP profile. To enable client flows, associate an authentication profile to the token profile or the SAML IDP profile.

When a flow begins, the client sends a request to protocol endpoints of the token profile. The following snippet shows the URL of an example front-channel request that the client sends using the system browser:

GET https://login.example.com/oauth/v2/oauth-authorize
    ?client_id=demo-client
    &redirect_uri=http://www.example.com/callback
    &response_type=code
    &scope=openid profile
    &code_challenge=WhmRaP18B9z2zkYcIlb4uVcZzjLqcZsaBQJf5akUxsA
    &code_challenge_method=S256
    &state=CfDJ8Nxa-YhPzjpBilDQz2C...

The Curity Identity Server validates the initial request against configuration and then returns a redirect response to the client. The redirect response sets a cookie that the browser must resend on all subsequent HTTP requests during user login. The redirect location depends on the client’s authentication policy. It begins an authentication workflow that can present a series of login forms to the user.

Authentication Endpoints#

Authentication endpoints are secure endpoints that can only be successfully called if the browser sends a secure cookie. For example, an Authenticator named htmlform1 presents its main login screen at a path of the following form:

https://login.example.com/authn/htmlform1

Similarly, an Authentication Action that presents a frontend form runs at a URL of the following form:

https://login.example.com/authn/authentication/_action/my_action

Anonymous Endpoints#

Anonymous endpoints do not require a secure cookie and are typically secured by another mechanism. For example, a password reset email link can execute in a new browser session and is secured by a one-time token (called a nonce). The following URL is an example of an anonymous endpoint.

https://login.demo.example/authn/anonymous/htmlform1/reset-password
    ?token=RKcAI6eQRgQbN6rOdCqTIRF9Td1xMChS

Registration Endpoints#

An authentication profile can be configured to allow users to register new accounts or couple devices to their identity. This is done at the registration endpoint. The path to create a resource will end with the string create and specify the authenticator ID that will handle the account registration and creation.

https://login.demo.example/authn/registration/htmlform1/create

Was this helpful?