The Fixiam Button enables users to authenticate to applications that do not natively support standard SSO protocols such as SAML or OIDC.

The integration uses OIDC behind the scenes.

Fixiam handles user authentication and issues an access token after successful authentication. The application owner is responsible for integrating the Fixiam login flow into their application, validating the access token, identifying the user, and creating the application's authenticated session.

How it works

User
  |
  | Clicks "Login with Fixiam"
  v
Customer Application
  |
  | Redirect
  v
Fixiam
  |
  | Authenticate user
  v
Fixiam
  |
  | Access Token
  v
Customer Application
  |
  | Validate token
  | Identify user
  | Create application session
  v
Authenticated User

Important: Fixiam does not create or manage the customer's application session. The application owner is responsible for handling the callback, validating the token, mapping the authenticated identity to an application user, and establishing the application's session.

Before You Start

Before starting the integration, make sure:

• You have administrative access to your Fixiam environment.
• You have access to the source code of the application you want to integrate.
• You can modify the application's login page.
• You can create or modify a callback endpoint in the application.
• You know which existing application users should authenticate through Fixiam.
• You know how your application currently manages user roles and permissions.

The application does not need to support SAML.

The application does not need to implement a full SSO platform.

However, the application must be able to integrate the Fixiam OIDC authentication flow and process the returned access token.

Step 1: Create the Application in Fixiam

Log in to your Fixiam administrator portal.

Navigate to:

Applications → Create Application

Enter the name of the application.

Example:

Application Name: Test OIDC Application

[SCREENSHOT PLACEHOLDER: Fixiam Create Application screen]

Screenshot: Show the Fixiam Application creation screen with the application name field.

Select OIDC as the authentication protocol.

Click Save.

Step 2: Configure the OIDC Application

After creating the application, Fixiam provides the OIDC configuration required by the application.

The configuration includes:

Fixiam OIDC application configuration showing Client ID, Client Secret, Issuer, Discovery URL and JWKS URI]

Security: Treat the Client Secret as sensitive information. Do not expose it in frontend code, public repositories, browser JavaScript, or client-side applications.

Step 3: Provide Application Configuration to Fixiam

The application owner must provide the following information when configuring the OIDC application:

Step 4: Create the Redirect URL

The Redirect URL is the endpoint in the customer's application that receives the authentication response from Fixiam.

For example:

https://example.com/auth/fixiam/callback

The customer application owner is responsible for creating this endpoint.

The URL must be registered in Fixiam.

Example flow

Fixiam
   |
   | Authentication successful
   v
https://example.com/auth/fixiam/callback

The application should process the authentication response at this endpoint.

Important: The Redirect URL must be an endpoint controlled by the application owner.

Step 5: Add the Login with Fixiam Button

Fixiam provides a login button that the application owner can add to the application's login page.

Example:

<a href="https://fixiam-lab.iam.seamfix.com/realms/fixiam-lab/protocol/openid-connect/auth?client_id=Test-oidc&response_type=token&redirect_uri=YOUR_REDIRECT_URL">
    <button style="font-weight: normal !important; padding: 16px 16px !important; background-color: #000CE4 !important; color: white !important; border:none; cursor:pointer">
        Login with Fixiam
    </button>
</a>

Replace:

YOUR_REDIRECT_URL

with the Redirect URL configured for the application.

Step 6: User Authentication

When a user clicks Login with Fixiam, the application redirects the user to Fixiam.

The user is then authenticated by Fixiam.

Customer Application
        |
        | Login with Fixiam
        v
      Fixiam
        |
        | User authentication
        v
 Authentication successful

Depending on the authentication configuration, the user may be required to provide additional authentication factors.

Step 7: Fixiam Returns the Access Token

After successful authentication, Fixiam redirects the user back to the configured Redirect URL.

The access token is returned in the URL fragment.

Example:

https://example.com/auth/fixiam/callback#access_token=eyJhbGc...

The returned access token is a JWT.

The application must securely process and validate the token before treating the user as authenticated.

Important: Do not trust the token simply because it was returned by the browser. The application must validate the JWT before granting access.

Step 8: Validate the Access Token

The application owner is responsible for validating the access token.

Fixiam provides a JWKS endpoint containing the public keys required to verify tokens issued by Fixiam.

Example:

https://fixiam-lab.iam.seamfix.com/realms/fixiam-lab/protocol/openid-connect/certs

The application should use a JWT/OIDC library appropriate for its programming language.

During validation, the application should verify the relevant JWT properties, including:

• Signature
• Issuer
• Audience
• Expiration
• Other claims required by the application's security policy

Node.js example

var jwt = require('jsonwebtoken');
var jwksClient = require('jwks-rsa');

var client = jwksClient({
    jwksUri: 'https://fixiam-lab.iam.seamfix.com/realms/fixiam-lab/protocol/openid-connect/certs'
});

function getKey(header, callback) {
    client.getSigningKey(header.kid, function(err, key) {
        var signingKey = key.publicKey || key.rsaPublicKey;
        callback(null, signingKey);
    });
}

jwt.verify(access_token, getKey, options, function(err, decoded) {
    if (err) {
        // Token validation failed
        return;
    }

    // Token is valid
});

Note: The application owner should configure the appropriate verification options for their application. Do not copy production configuration blindly from this example.

Step 9: Identify the Application User

After validating the token, the application needs to determine which existing application user the authenticated identity represents.

For example:

Fixiam identity
      |
      v
[email protected]
      |
      v
Customer Application
      |
      v
Existing user:
Jumoke
      |
      v
Role:
IT

The application owner is responsible for implementing this user mapping.

Fixiam authentication confirms who the user is.

The application determines which local account that identity corresponds to.

Step 10: Create the Application Session

Once the application has:

1. Validated the Fixiam access token.
2. Identified the user.
3. Confirmed that the user is allowed to access the application.

The application should create its normal authenticated session.

Fixiam Token
     |
     v
Token Valid
     |
     v
User Identified
     |
     v
Existing Application Account
     |
     v
Application Session
     |
     v
User Logged In

The application continues to use its existing session management mechanism.

Fixiam does not replace the application's internal session management.

Authentication and Authorization

It is important to understand the difference between authentication and authorization.

Authentication

Fixiam answers:

Who is this user?

For example:

Jumoke
[email protected]

Authorization

The application answers:

What is this user allowed to do?

For example:

User: Jumoke
Role: IT

Permissions:
✓ View users
✓ Manage devices
✓ View reports
✗ Manage billing

Fixiam authenticates the user.

The application continues to enforce its own roles and permissions.

Complete Authentication Flow

The complete flow is:

1. User opens the application
           |
           v
2. User clicks "Login with Fixiam"
           |
           v
3. Application redirects user to Fixiam
           |
           v
4. Fixiam authenticates the user
           |
           v
5. Fixiam issues an access token
           |
           v
6. Fixiam redirects user to the application
           |
           v
7. Application receives the token
           |
           v
8. Application validates the token
           |
           v
9. Application identifies the user
           |
           v
10. Application creates its session
           |
           v
11. Application applies the user's existing permissions
           |
           v
12. User accesses the application

Responsibility Matrix

Security Considerations

The application owner should follow these security requirements:

Protect the Client Secret

Never expose the Client Secret in:

• Frontend JavaScript
• HTML
• Mobile client code
• Public repositories
• Browser storage

Validate every token

The application should validate the token before accepting it as proof of authentication.

Validate the token issuer

The application should confirm that the token was issued by the expected Fixiam issuer.

Validate the audience

The application should confirm that the token was issued for the intended application.

Check token expiration

Expired access tokens must not be accepted.

Use HTTPS

The Redirect URL and application endpoints should use HTTPS in production.

What the Application Owner Needs to Implement

Before going live, the application owner should have completed the following:

• Created the Redirect URL
• Added the Login with Fixiam button
• Configured the Fixiam Client ID
• Securely stored the Client Secret where applicable
• Configured the Fixiam Issuer
• Configured the OIDC Discovery URL
• Implemented the callback endpoint
• Implemented JWT validation
• Configured the JWKS URI
• Implemented Fixiam identity to application user mapping
• Implemented application session creation
• Confirmed existing roles and permissions continue to work
• Tested successful authentication
• Tested failed authentication
• Tested expired tokens
• Tested logout
• Tested an unauthorized application user

Troubleshooting

User is redirected to Fixiam but cannot authenticate

Check:

• The user exists in Fixiam.
• The user is active.
• The user has access to the application.
• The application configuration is correct.

Fixiam authentication succeeds but the user cannot access the application

Check:

• The Redirect URL is correct.
• The callback endpoint is working.
• The application is receiving the access token.
• The JWT is being validated successfully.
• The Fixiam identity matches an existing application user.
• The user has the required application role.

Token validation fails

Check:

• The JWKS URI is correct.
• The Issuer is correct.
• The Audience is correct.
• The token has not expired.
• The application is using the correct JWT validation library.
• The application's server can reach the JWKS endpoint.

Integration Summary

The Fixiam Button provides a way for applications that do not natively support standard SSO protocols to use Fixiam for user authentication.

The integration requires cooperation between Fixiam and the application owner.

Fixiam provides the identity and authentication layer.

The application owner integrates the authentication response and remains responsible for the application's session, user mapping, roles, and permissions.

                    FIXIAM
                      |
              Authentication
                      |
                Access Token
                      |
                      v
             CUSTOMER APPLICATION
                      |
              Token Validation
                      |
               User Mapping
                      |
            Application Session
                      |
                Authorization
                      |
                      v
                 APPLICATION

Current integration model: The application owner performs the required application-side integration.