Magic links are a common passwordless authentication method. This page dives into the concept, explores common use cases, and guides you on how to implement this feature with Entrypage, using PKCE.

Prerequisites:

A magic link is a unique, time-sensitive URL securely tied to a specific user account. When clicked, this link instantly authenticates the user, granting them access without needing a password.

Key characteristics of magic links are:

  • They are time-bound, expiring after a short period.
  • They are unguessable, thanks to their complex, random nature.
  • They are single-use, meaning they can only be clicked once for authentication.

Adopting magic links significantly boosts security and enhances the user experience.

Typically delivered via email or SMS, a single click on a magic link logs the user in immediately. This eliminates the need for traditional login pages and the inherent vulnerabilities associated with passwords.

Consider this: passwords, by their nature, are long-lived and frequently become compromised in data breaches, making them susceptible to brute-force attacks. Furthermore, managing forgotten credentials is a common headache for both users and developers, often leading to social engineering risks.

By embracing magic links, you effectively eliminate all these common attack surfaces, offering a more secure and hassle-free authentication method.

Common use-cases

Magic links are not new; they are already a widely adopted and proven authentication method. Common use cases include:

E-commerce

Online shoppers frequently forget their usernames and passwords, leading to frustration and abandoned carts. By integrating magic links, a user’s email address becomes their direct path to authentication. This creates a much smoother sign-in experience, ensuring users can complete their purchases without the friction of a forgotten password reset.

Collaborative Tools and SaaS Applications

For productivity and collaboration platforms (like project management tools, document editors, or communication apps), magic links simplify onboarding and ongoing access. New users can jump straight into a shared workspace without the hurdle of password creation, and existing users can quickly log in, especially when switching devices or browsers.

Event Registration and Ticketing

Magic links can provide direct, secure access to event details, tickets, or personalized dashboards. After registration, a magic link can be emailed to attendees, allowing them to view their QR code, modify their registration, or access event-specific content without remembering a password. This is particularly useful for one-off events where password fatigue might be high.

Account Recovery and Passwordless Reset

Even for services that still rely on passwords, magic links are an excellent method for passwordless recovery. If a user forgets their password, instead of sending a temporary password or forcing a complex reset process, a magic link can be sent to their verified email or phone, allowing them to directly sign in or set a new password securely.

Entrypage provides a range of robust authentication methods, each offering distinct security advantages:

  • Magic Links: For easy, passwordless access via email or SMS.
  • WebAuthn: Leveraging advanced hardware security like Windows Hello, Touch ID, Face ID, or FIDO2 keys for strong, phishing-resistant authentication.
  • TOTP (Time-based One-Time Passwords): Such as those generated by authenticator apps, providing an extra layer of security.

These methods are designed to be complementary. Entrypage allows you to define a security policy for your entire domain. For instance, you can configure your domain so that after a user authenticates with a magic link, they must also use WebAuthn for an even stronger level of assurance.

Ultimately, “secure enough” depends on the nature of the information your application handles. Compliance regulations like GDPR require you to implement security measures appropriate to the personal and sensitive data you process. We recommend carefully assessing the type of information you’re dealing with and its context to determine if using only magic links meets your specific security requirements.

Entrypage makes it simple to use Magic Links for authentication. To create a magic link, you’ll first need to set up a local user within Entrypage. Please note that magic links are designed for these local accounts and are not currently supported for accounts authenticated via external providers like Google or GitHub or other federated accounts.

You have two ways to create a magic link:

Step 1: Create a Local User

First, you’ll need to create the local user that the magic link will be tied to. Here’s an example using our API:

curl -X 'POST' \
  'https://api.entrypage.io/v1/domain/your-domain-here/user' \
  -H 'accept: text/plain' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
  "preferredUsername": "fred@yourdomain.com",
  "name": "Fred Johnson"
}'

You must provide a preferredUsername (typically an email address) and a name for the user. A successful request will return the subject ID (sub) of the newly created user, like this:

{
  "sub": "00000000000000000000000000000000"
}

Once you have the user’s sub ID, you can generate the magic link:

curl -X 'POST' \
  'https://api.entrypage.io/v1/domain/your-domain-here/user/00000000000000000000000000000000/magiclink' \
  -H 'accept: text/plain' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
  "redirectUri": "https://www.yourwebsite.com/login"
}'

This request includes a redirectUri. This is the specific page on your website where the user will land immediately after successfully authenticating with the magic link. It’s like a designated arrival point, distinct from the technical “OAuth redirect URI” used in broader authorization flows.

A successful request to generate the magic link will yield the link itself:

{
  "uri": "https://auth.yourwebsite.com/account/link/1234567890123456789012345678901234567890"
}
Step 3: User Authentication Flow

When a user clicks on the magic link you’ve generated and sent to them, the following process begins:

  1. Session Initiation: The magic link first signs the user into your Entrypage authorization server, initiating a secure HTTP session.
  2. Redirection: After the session is established, the user is automatically forwarded to the redirectUri you provided when creating the link.

This redirectUri can be any page on your site. For example, it could be a deep link to specific content, or it might be your application’s login endpoint, which then initiates your standard OAuth authorization sequence (handling challenges and sending the user to the /authorize endpoint to finalize their application login).

The entire authentication flow is illustrated in the following diagram:

Flow Diagram 

sequenceDiagram
    Application->>+Entrypage API: Create User Request
    Entrypage API->>-Application: User Subject ID
    Application->>+Entrypage API: Create Magic Link Request for User
    Entrypage API->>-Application: Magic Link URI
    Application->>User: Send Magic Link (e.g., via email/SMS)
    User->>+Entrypage Authorization Server: Click Magic Link (Authenticate)
    Entrypage Authorization Server->>-Application: Redirect User (to redirectUri)
    Application->>+Entrypage Authorization Server: Initiate OAuth Login Sequence (e.g., via /authorize endpoint)
    Entrypage Authorization Server->>-Application: Return Authorization Code
    Application->>+Entrypage Authorization Server: Exchange Code for Tokens
    Entrypage Authorization Server->>-Application: Return ID Token & Access Token

Entrypage enforces the use of PKCE (Proof Key for Code Exchange) by default.

In a standard PKCE flow, the client application (where the user is signing in) first creates a unique “challenge.” This challenge is stored by the client and later used to exchange the authorization code for a pair of tokens, ensuring that only the legitimate client can complete the authentication process.

Entrypage’s approach to magic links offers a distinct advantage compared to many other Identity as a Service (IDaaS) platforms. We do not force a full OAuth 2.0 Authorization Code Flow that redirects the user to an OAuth redirect_uri with a code in the query string. This is a deliberate choice: we want to ensure you can make use of PKCE (Proof Key for Code Exchange) with magic links, without enforcing a specific OAuth flow as a prerequisite for magic link authentication itself. In contrast, many other IDaaS platforms often require an OAuth 2.0 Authorization Code Flow as a required step for magic links.

Consequently, when using magic links with Entrypage:

  • The user first authenticates directly with the Entrypage authorization server.
  • You have the flexibility to choose where to redirect the user after successful authentication. We don’t force an immediate sign-in to your application, giving you more control over the user journey.

Conclusion

Magic links offer a secure and user-friendly approach to authentication, moving beyond the vulnerabilities and friction of traditional passwords. By leveraging Entrypage’s API, you can integrate magic links into your applications.

Disclaimer