# Breeze DOCS > Documentation for Breeze This file contains all documentation content in a single document following the llmstxt.org standard. ## Breeze Access Coming Soon! --- ## Authentication Authentication in Breeze helps you control how users access the platform and manage their login experience. This page gives you an overview of the authentication features available and points you to detailed guides. ## What is Authentication? Authentication is the process of verifying a user's identity when they log in to Breeze. It ensures that only authorized users can access your organization's data and features. ## Authentication Features ### Single Sign-On (SSO) Single Sign-On (SSO) allows users to access Breeze using their existing organizational credentials. Instead of creating separate Breeze accounts, users can log in once with their company credentials and gain access to Breeze seamlessly. **Key Benefits:** - **Convenience**: Users only need to remember one set of credentials - **Security**: Reduces password-related security risks - **Efficiency**: Eliminates the need for multiple logins - **User Experience**: Provides seamless access to Breeze Breeze supports SSO integration with: - **Azure Active Directory (Azure AD)** - Available out of the box - **Other Identity Providers** - Available upon request (SAML, OAuth2, or OpenID Connect) :::info **SSO Availability**: SSO is available for Enterprise plans only. Contact your dealer or Breeze representative to learn more about our Enterprise plans. ::: ### OAuth API Authentication OAuth API Authentication enables secure, programmatic access to the Breeze API using industry-standard OAuth 2.0 tokens. This authentication method is designed for machine-to-machine integrations, automated systems, and service-to-service communication. **Key Benefits:** - **Security**: Short-lived tokens (1 hour default) reduce exposure if compromised - **Standards-Based**: Uses industry-standard OAuth 2.0 Client Credentials flow - **Flexible**: Supports automated workflows, integrations, and scheduled jobs - **Auditable**: All authentication events are logged for security and compliance **Use Cases:** - External system integrations - Automated reporting and data synchronization - CI/CD pipeline access - Partner API access - Service-to-service communication ## Getting Started To learn more about setting up and managing authentication in Breeze, explore the following sections: - **[OAuth API Authentication](./oauth-api-authentication.mdx)** - Authenticate API requests using OAuth 2.0 - **[SSO Overview](./sso/sso-introduction.md)** - Introduction to Single Sign-On - **[SSO Setup Guides](./sso/sso-setup-azure-ad.md)** - Step-by-step instructions for configuring SSO - **[SSO User Onboarding](./sso/sso-user-onboarding.md)** - Streamline user onboarding with SSO - **[SSO Role Management](./sso/sso-role-management.md)** - Manage user roles with SSO ## Common Tasks - Authenticate API requests using OAuth 2.0 tokens - Set up SSO integration with your identity provider - Configure user onboarding workflows - Manage user roles and access permissions - Create custom SSO login routes - Monitor authentication activity For detailed instructions on these tasks, see the [SSO documentation](./sso/sso-introduction). --- ## OAuth API Authentication OAuth API Authentication enables secure, programmatic access to the Breeze API using industry-standard OAuth 2.0 tokens. This authentication method is designed for machine-to-machine integrations, automated systems, and service-to-service communication where applications need to access the API without user interaction. ## When to Use This Use OAuth API Authentication when you need to: - Integrate external systems with Breeze programmatically - Build automated workflows that access the API - Create service-to-service integrations - Access the API from scripts, scheduled jobs, or background services - Replace API key authentication with a more secure, standards-based approach This authentication method is ideal for: - Payment processor integrations - Automated reporting systems - CI/CD pipeline integrations - Partner API access - Mobile or desktop application backends ## Before You Start To use OAuth API Authentication, you need: - **OAuth Client Credentials**: A `client_id` and `client_secret` obtained from an administrator (see [OAuth Client Management](/docs/user-administration/oauth-client-management)) - **API Access**: The OAuth client must be associated with a user account that has appropriate roles for your required operations - **HTTPS Connection**: Always use HTTPS in production environments :::info[Required for Setup] **Creating OAuth Clients**: Only users with `Super administrator` role can create OAuth clients. See [OAuth Client Management](/docs/user-administration/oauth-client-management) for more information. ::: ## How OAuth Authentication Works OAuth API Authentication uses the OAuth 2.0 Client Credentials flow, which is designed for machine-to-machine communication. Here's how it works: ### Overview 1. **Obtain Credentials**: Get `client_id` and `client_secret` (see [OAuth Client Management](/docs/user-administration/oauth-client-management)) 2. **Request Access Token**: Exchange credentials for a short-lived access token 3. **Use Access Token**: Include the token in API requests to authenticate 4. **Refresh Token**: Request a new token before expiration (tokens cannot be refreshed) ### Step 1: Obtain OAuth Client Credentials 1. Create an OAuth client associated with a user account 2. Provide you with: - **Client ID**: A unique identifier (format: `oauth_xxx`) - **Client Secret**: A secure secret string (shown only once during creation) **Important**: Store these credentials securely. Never commit them to version control or share them insecurely. ### Step 2: Request an Access Token To authenticate, send a POST request to the token endpoint: **Endpoint**: `POST /oauth/token` **Request Format**: ```json { "grant_type": "client_credentials", "client_id": "oauth_abc123...", "client_secret": "your_secret_here", "scope": "read:credentials write:credentials" } ``` **Parameters**: - `grant_type`: Must be `"client_credentials"` (required) - `client_id`: Your OAuth client ID (required) - `client_secret`: Your OAuth client secret (required) - `scope`: Optional space-separated list of scopes (permissions are determined by the user's roles, not scopes) **Response**: ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "" } ``` **Response Fields**: - `access_token`: JWT token to use for API authentication (valid for 1 hour by default) - `token_type`: Always `"Bearer"` - `expires_in`: Token lifetime in seconds (default: 3600 = 1 hour) - `scope`: Space-separated list of granted scopes ### Step 3: Use the Access Token Include the access token in all API requests using the `Authorization` header: ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Example API Request**: ```bash curl https://api.domain.com/graphql \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{"query": "{ CredentialV1(credentialId: \"...\") { _id name } }"}' ``` ### Step 4: Handle Token Expiration Access tokens expire after 1 hour (default). Before expiration: 1. **Request a New Token**: Use the same `/oauth/token` endpoint with your client credentials 2. **Update Your Application**: Replace the old token with the new one 3. **Implement Token Caching**: Cache tokens and refresh them proactively (e.g., 5 minutes before expiration) **Best Practice**: Request a new token before the current one expires to avoid service interruption. ## Permissions and Authorization ### How Permissions Work OAuth client permissions are determined by the **user account** associated with the client, not by OAuth scopes. When the an OAuth client is created, it is associated with a specific user account. The client inherits all permissions from that user's roles. **Important**: The OAuth client can only access resources within the tenant of the associated user account. ### OAuth Scopes OAuth scopes are currently not used for permissions. They are reserved for future use. ## Token Management Best Practices ### Token Caching - **Cache tokens** to reduce token requests and improve performance - **Track expiration** and refresh tokens proactively (5 minutes before expiration) - **Store tokens securely** in memory or secure storage (never in logs or error messages) ### Error Handling - **Handle token expiration**: Implement automatic token refresh when you receive 401 Unauthorized responses - **Handle rate limits**: If you receive 429 Too Many Requests, implement exponential backoff - **Log errors appropriately**: Never log tokens or client secrets ### Security - **Store secrets securely**: Use environment variables or secret management systems - **Rotate secrets**: Rotate client secrets regularly (every 90 days recommended) - **Monitor usage**: Track token usage and authentication failures ## Rate Limiting The OAuth token endpoint has rate limiting to prevent abuse: - **Default limit**: 100 requests per hour per client - **Window**: 1 hour (3600 seconds) - **Tracking**: Per `client_id` **Best Practices**: - Implement token caching to minimize token requests - Reuse tokens until expiration - If you hit rate limits, reduce request frequency or contact support for custom limits ## Common Issues and Solutions ### "Invalid client credentials" **Possible causes**: - Incorrect `client_id` or `client_secret` - Client has been revoked or is inactive - Client secret has been rotated (use the latest secret) **Solutions**: - Verify credentials are correct (no extra spaces or encoding issues) - Check with your administrator that the client is active - Request new credentials if the secret was rotated ### "Token validation failed" **Possible causes**: - Token has expired - Incorrect `Authorization` header format - Token signature is invalid **Solutions**: - Request a new token (tokens expire after 1 hour) - Ensure header format is: `Authorization: Bearer ` - Verify you're using the latest token ### "Rate limit exceeded" **Possible causes**: - Too many token requests in a short time - Not caching tokens between requests **Solutions**: - Implement token caching - Reduce token request frequency - Wait for the rate limit window to reset (1 hour) ### "Insufficient permissions" **Possible causes**: - Associated user account lacks required roles - User account has been deactivated - Accessing resources outside the user's tenant **Solutions**: - Verify the associated user account has the required roles - Check with your administrator to update user roles if needed - Ensure you're accessing resources within the correct tenant ## What's Next? - [OAuth Client Management](/docs/user-administration/oauth-client-management) - Learn how administrators create and manage OAuth clients - [User Administration Overview](/docs/user-administration/) - Explore user administration features - [SSO Overview](./sso/sso-introduction.md) - Learn about Single Sign-On for user authentication --- ## Azure Entra ID Setup for SSO :::warning Beware that this documentation may be outdated or differ from your version of the external service. Please refer to the official documentation provided by the external service for the most accurate information. Breeze does not provide support for setting up external services, and does not take responsibility for any issues that may arise from following this documentation. ::: Creating an application in Azure for Single Sign-On (SSO) federation to your platform enables users to access multiple services with one set of login credentials, streamlining the authentication process and enhancing security. This step-by-step documentation will guide you through creating an Azure Active Directory (Azure AD) application and configuring it for SSO in order to integrate with Breeze. ## Prerequisites - **Azure Subscription:** You need an active Azure subscription. - **Azure Active Directory:** Your Azure subscription must have Azure Active Directory (AD) / Azure Entra ID enabled. - **Admin Access:** You must have administrative privileges in Azure AD to create and configure applications. ## Step 1: Register a New Application in Azure AD 1. **Log into the Azure Portal:** Navigate to [https://portal.azure.com](https://portal.azure.com) and sign in with your admin account. 2. **Access Azure Entra ID:** From the left-hand side menu, select “Azure Entra ID”. This is your organization's directory service. 3. **Go to App Registrations:** Find and click on “App registrations” to see a list of your applications. 4. **Register a New Application:** Click on “New registration” at the top. This step is about telling Azure AD about your new application, so it knows how to handle authentication for it. 5. **Configure Application Settings:** - **Name:** Enter a descriptive name for your application. - **Supported account types:** Choose who can use this application. For SSO across organizations, you might select “Accounts in any organizational directory”. - **Redirect URI (optional):** Enter the URI where Azure AD will send responses to your authentication requests. You will receive this URL from the Breeze team! 6. **Register:** Click on the “Register” button to create the application. This action generates a unique `Application (client) ID` for your application; note it down as it will be used later in the integration process. ## Step 2: Configure Azure AD for OpenID Connect 1. **Access Your Application:** Go back to “App registrations” in Azure AD and select the application you previously registered. 2. **Find and Configure Authentication:** In the application's menu, locate and select `Authentication`. This section allows you to set up how your application will authenticate users, which in this case will be via OpenID Connect. 3. **Configure Redirect URIs:** - A Web Platform should already exist here with a Redirect URI if you completed Step 1. If not, follow these steps: - Click on “Add a platform” and choose “Web” as the platform type. This indicates that your application will authenticate users from a web application. - In the “Redirect URIs” field, enter the URL you have received from the Breeze Team. **NOTE**: You may have to enter this at a later stage as the URL is not known until the SSO Integration is completed. 4. **Enable ID Tokens:** - Find the `Implicit grant and hybrid flows` section and check the box for `ID tokens (used for implicit and hybrid flows)`. This enables your application to receive ID tokens directly from Azure AD, which are crucial for OpenID Connect authentication. 5. **Save the Configuration:** After making these adjustments, click “Save” to apply your changes. Azure AD is now configured to use OpenID Connect for authenticating users to your application. 6. **Obtain Application (client) ID and Directory (tenant) ID:** - Note down the `Application (client) ID` and `Directory (tenant) ID` displayed on your application’s overview page. These are needed to configure your platform to authenticate with Azure AD using OpenID Connect. ## Step 3: Assign Users and Groups through Enterprise Applications 1. **Navigate to Enterprise Applications:** Since the "Users and groups" option is not directly available under the App registrations menu for your application, you need to access it through "Enterprise Applications." In the Azure portal, from the left-hand side menu, select "Azure Entra ID" and then choose "Enterprise applications." This section lists all the applications that are available for your organization, including the one you've just registered. 2. **Select Your Application:** Find the application you registered in Step 1 by searching for its name in the list of enterprise applications. Click on your application's name to open its configuration settings. 3. **Access Users and Groups:** Within your application's overview page, look for the "Users and groups" section. This is where you can manage who has access to your application. By assigning users and groups here, you control which individuals or groups within your organization can use the application to authenticate. 4. **Assign Users/Groups:** Click on "Add user/group" to start adding users or groups to your application. This step is crucial for defining who will have access to your platform through Azure AD's Single Sign-On (SSO) capabilities. - **Choose Users/Groups:** In the dialog that appears, you can search for and select the users or groups you wish to add. You can add individual users or entire groups, depending on your needs. - **Assign:** After selecting the users or groups, click "Select" and then "Assign" to finalize the process. The selected users or groups are now granted access to your application, enabling them to use SSO to log in to your platform. ## Step 4: Collect and send the following information to the Breeze Support Team: - **Application (client) ID:** The unique identifier for your application in Azure AD. - **Directory (tenant) ID:** The unique identifier for your organization's directory in Azure AD. - **Client secret:** A secure key that your application uses to authenticate with Azure AD. This is generated in the Azure portal under your application's "Certificates & secrets" section. :::danger Make sure to keep the client secret secure and do not share it with unauthorized individuals. This key is essential for your application to authenticate with Azure AD and should be treated as sensitive information. Send this information securely to the Breeze Support Team to complete the SSO integration. ::: ## Optional: Role assignment If you want to assign roles to users based on their Azure AD group membership, you can do so by following these steps: 1. **Access Your Application:** Go back to the application you registered in Azure AD. 2. **Find and Configure `Manifest`:** In the application's menu, locate and select `Manifest`. This section allows you to edit the application's manifest file, which contains the configuration settings for your application. 3. **Add Role Assignments:** - In the manifest file, locate the `appRoles` section and add the roles you want to assign to users based on their Azure AD group membership. For example: ```json "appRoles": [ { "allowedMemberTypes": [ "User" ], "description": "Will be able to manage users in Breeze", "displayName": "Breeze User Administrator", "id": "f5726e54-b16d-483b-9847-4949c4517cfe", "isEnabled": true, "lang": null, "origin": "Application", "value": "userAdministration" }, { "allowedMemberTypes": [ "User" ], "description": "Will get the Admin Role in Breeze", "displayName": "Breeze Administrator", "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c661", "isEnabled": true, "lang": null, "origin": "Application", "value": "admin" } ], ``` - **Note:** The `id` field should be a unique identifier for each role. You can generate a GUID for this purpose. - **Note:** The `value` field is the role name that will be assigned to users. This must match the role name in Breeze. For a list of available roles in Breeze, contact the Breeze Support Team. 4. **Save the Manifest:** After adding the role assignments to the manifest file, click “Save” to apply your changes. Azure AD is now configured to assign roles to users based on their group membership. 5. Configure the role assignment in Breeze. See [SSO Role Management](#) for more information. ## Conclusion By completing these steps, you have successfully created an application in Azure for SSO federation to your platform. This setup enhances your platform's security and user experience by streamlining the login process. Remember to regularly review and update your SSO configuration to keep it secure and functional. --- ## Single Sign-On (SSO) - Introduction Breeze supports Single Sign-On (SSO) for your organization. Single Sign-On (SSO) is a user authentication process that allows a person to access multiple applications with one set of login credentials. This means that users can log in once and gain access to a variety of systems without being prompted to log in again for each one. :::info **SSO Availability**: SSO is available for Enterprise plans only. Contact your dealer or Breeze representative to learn more about our Enterprise plans. ::: ## Benefits of SSO - **Convenience**: Users only need to remember one set of credentials, making it easier to log in and reducing password fatigue. - **Efficiency**: Saves time by eliminating the need to log in multiple times. - **Security**: Reduces the number of passwords users need to remember and manage, lowering the risk of password-related security breaches. - **User Experience**: Enhances the overall user experience by providing seamless access to multiple applications. ## SSO Integration with Breeze In Breeze, we currently support SSO integration with Azure Active Directory (Azure AD) **out of the box**. Additionally, we can add support for other identity providers (IdPs) upon request, as long as they use SAML, OAuth2, or OpenID Connect (OIDC) standards. ## Advanced Features with SSO Breeze offers advanced features in combination with SSO, such as: - **User Onboarding**: Streamlines the process of adding new users. - **Role Management**: Simplifies the assignment and management of user roles. - **SSO Route**: Custom direct route for users to log in using SSO. For more information on these features, please refer to the following sections: - [User Onboarding](docs/authentication/sso/sso-user-onboarding.md) - [Role Management](docs/authentication/sso/sso-role-management.md) - [Custom SSO Route](docs/authentication/sso/sso-route.md) Explore our documentation to learn how to set up and use SSO with Breeze, and to take full advantage of these powerful authentication features. --- ## SSO Role Management # Role management via SSO ## Introduction Single Sign-On (SSO) Role Management in Breeze allows you to automatically assign and update roles to users based on their identity provider (IdP) credentials. This ensures that users have the appropriate permissions and access rights when logging in via SSO. :::note The default behavior with SSO authentication methods is just to assign base roles to new users. To further integrate role management from the IdP, you can set up SSO Role Management in Breeze. This is described in this guide. ::: This guide provides instructions on how to configure SSO Role Management in Breeze. ## Prerequisites Before setting up SSO User Onboarding, ensure that an SSO integration is already set up in Breeze. For more information on setting up SSO, refer to the [Setup Azure AD/ Entra ID](docs/authentication/sso/sso-setup-azure-ad.md). :::warning Any changes performed in the SSO Role management configuration will take immediate effect. Ensure that you have tested the configuration in a non-production environment before applying it to a production environment. Consider communicating with your users before making changes to the SSO Role management configuration to avoid any disruptions. ::: ## Configuration ### Default Configuration By default, all users created via SSO will be assigned the `User` role. No other role management is performed. ### Changing Base Roles Base roles are the roles that will be assigned to all users created via SSO. The default role is `User`. This is the default behavior and will be applied to all users unless a more specific role is assigned based on the IdP response. Changing the Base Roles will **NOT** affect existing users. It will only apply to new users created via SSO. 1. **Navigate to Tenant Settings**: In the Breeze admin portal, go to the `Tenant settings` page. 2. **Open Security Settings**: Select the `Security settings` tab and click on `Edit security settings`. 3. **Configure SSO Settings**: In the `SSO Settings` section, click the `Change Settings` button. 4. **Locate** the `Role management` section and click on the `Change Settings` button. 5. **Select** the desired `Base Roles` using the `Select roles` button. A dialog will appear with a list of available roles. 6. **Save** the changes. For a more advanced and dynamic setup, read on below. ### Setting up Role management via SSO Breeze allows for more advanced role management via SSO. This is done by mapping roles from the IdP response to Breeze roles. Setting up role management via SSO will ensure that users are assigned the correct roles based on their IdP credentials. Any changes in the IdP will be reflected in Breeze the next time the user logs in. :::important The roles must be provided in the IdP response in order to be mapped to Breeze roles. We have provided an example guide on how to do this in Azure Entra ID, see [Azure Role assignment](/docs/authentication/sso/guide-setup-external/azure-entra-id.md#optional-role-assignment). ::: To setup dynamic Role Management in Breeze, the following steps are required: 1. **Navigate to Tenant Settings**: In the Breeze admin portal, go to the `Tenant settings` page. 2. **Open Security Settings**: Select the `Security settings` tab and click on `Edit security settings`. 3. **Configure SSO Settings**: In the `SSO Settings` section, click the `Change Settings` button. 4. **Locate** the `Role management` section and click on the `Change Settings` button. 5. **Enable** the `Role management` setting. 6. **Configure** as needed, see more details below. #### Settings details | Setting | Description | |-------------------------------------------------------|-------------| | [**SSO Max Role**](#sso-max-role) | The highest possible role-level the IdP can assign users. | | [**Strict Role management**](#strict-role-management) | If enabled, users roles can only be assigned/updated by the IdP. | | [**Restricted roles**](#restricted-roles) | A list of roles that cannot be assigned by the IdP. | #### SSO Max Role The `SSO Max Role` setting specifies the highest possible role-level the IdP can assign users. If the IdP response contains one or more roles that is higher than the `SSO Max Role`, these will be ignored. :::note The dropdown list will only show roles that are the same or higher that **YOUR** current role. If you need a higher role, please contact Breeze Support or a know user with the correct role. If the SSO profile is already set up with a `SSO Max Role` that is higher than your current role, you will not be able to update the Role Management settings at all. ::: #### Strict Role management The `Strict Role management` setting specifies if users roles can only be assigned/updated by the IdP. :::important When this is enabled, it will not be possible to update SSO users roles manually in Breeze. ::: #### Restricted roles The `Restricted roles` setting specifies a list of roles that cannot be assigned by the IdP. Use the `Select roles` button to select the roles that should be restricted. #### Allow only one active account Check this box to allow only one active account per user. If a user is already active on a different tenant under the same SSO Auth profile, they will be deactivated before the new user is activated/created. This may happen if the SSO is set up with a dynamic tenant mapping, or if the static tenant has changed since the user was created. This setting is available for both `Static` and `Dynamic` mapping types. --- ## Custom SSO Route ## Introduction A custom route for Single Sign-On (SSO) allows you to create a unique URL for users to log in using SSO. This feature is useful for organizations that want to customize the login experience for their users. It will also make the login experience more intuitive and user-friendly as the user do not have to first enter their email address in the Breeze login page before being redirected to the IdP login page. This guide provides instructions on how to configure a custom SSO route in Breeze. ## Prerequisites Before setting up SSO User Onboarding, ensure that an SSO integration is already set up in Breeze. For more information on setting up SSO, refer to the [Setup Azure AD/ Entra ID](docs/authentication/sso/sso-setup-azure-ad.md). ## Configuration ### Default Configuration By default, the SSO route is not customized. Users can log in using the default normal login flow in Breeze. ### Configuring a Custom SSO Route To enable automatic user onboarding, the following steps are required: 1. **Navigate to Tenant Settings**: In the Breeze admin portal, go to the `Tenant settings` page. 2. **Open Security Settings**: Select the `Security settings` tab and click on `Edit security settings`. 3. **Configure SSO Settings**: In the `SSO Settings` section, click the `Change Settings` button. 4. **Locate** the `Custom SSO Route` section and click on the `Change Settings` button. 5. **Enter** the desired custom route in the `Custom SSO Route` field. Must be a single word that will be appended to the SSO route. For example, if the custom route is `mycompany`, the SSO route will be `https://breeze.idportal.no/sso/mycompany`. :::important The route value must be a unique single word, URL compatible string that will be appended to the SSO route. E.g. `mycompany`, `mycompany123`, `mycompany-123`, `mycompany_123` are all valid. We strongly recommend that you use a value that is unique to your organization to avoid conflicts with other tenants. ::: :::warning We preserve the right to change the route if it conflicts with other tenants and you cannot show that you have the right to use the route. For example using a know trademarked name like `microsoft` or `google` without being able to show that you have the right to use it. ::: After saving the custom route, you should be able to visit `https://breeze.idportal.no/sso/{custom-route}` to log in using the SSO authentication method. --- ## SSO Setup - Azure AD / Entra ID ## Overview This document provides instructions on how to set up Single Sign-On (SSO) for Breeze using Azure Active Directory (Azure AD) / Azure Entra ID. SSO allows users to log in to Breeze using their organization's credentials. ## Prerequisites - Breeze Tenant/Portal is created and ready. - Azure Entra ID SSO Setup is ready (See [Azure Entra ID Setup for SSO](docs/authentication/sso/guide-setup-external/azure-entra-id.md)). - Terms and Conditions are accepted by the customer (prices may apply). ## Access Conditions In order for your users to log in to Breeze, they first MUST be allowed to use the Azure Entra ID SSO application. This is done by assigning users to the application within Azure Entra ID. By default, users will **not** automatically have access to Breeze. There are a couple of strategies to assign access to Breeze for the company users: - **Default strategy**: The user must first be created in Breeze by an admin. The user will then be able to log in to Breeze using the Azure Entra ID SSO, assuming they have been assigned to the application in Azure Entra ID and the user's email in Breeze matches the email in Azure Entra ID. - **Automatic strategy**: The user will be automatically created in Breeze the first time they log in using the Azure Entra ID SSO. This requires that the user has been assigned to the application in Azure Entra ID. For more information, see [SSO User Onboarding](#sso-user-onboarding). ## Required Information The setup in Breeze will be done by Breeze Support. The following information is required for the setup: - **Application (client) ID:** The unique identifier for your application in Azure AD. - **Directory (tenant) ID:** The unique identifier for your organization's directory in Azure AD. - **Client secret:** A secure key that your application uses to authenticate with Azure AD. This is generated in the Azure portal under your application's "Certificates & secrets" section. ## Configuration Steps :::note[Required roles] **Required roles**: `System Administrator` To perform the following steps, you need to have the roles listed above. ::: :::danger Make sure to have the required information ready before proceeding with the following steps. Setting up an SSO integration will change the way your users log in to Breeze. Make sure to communicate this change to your users. Additional steps are required to enforce the SSO login for your users. Please refer to the [Enforce SSO for all users](#enforce-sso-for-all-users) section for more information. ::: The following steps are required to set up SSO for Breeze. This is done by the Breeze Team only. 1. **Gather Required Information**: Make sure to have the required information ready (see [Prerequisites](#prerequisites)). 2. **Navigate** to the Breeze Tenant/Portal and go to the `Tenant settings` page. 3. **Open** the `Security settings` tab and click on the `Edit security settings` button. 4. **Find** the `SSO Settings` section and click on the `Change Settings` button. 5. **Enter** the required information in the fields provided and hit the `Save` button. 6. **Login** to Breeze using the Azure Entra ID SSO to test the setup. By default, the usage of the SSO is optional for the users, see [Enforce SSO for all users](#enforce-sso-for-all-users) for more information. ## What's Next Congratulations! You have successfully set up SSO for Breeze using Azure Entra ID. To further enhance and take advantage of the Breeze SSO integration, you can explore the following features: ### Enforce SSO for all Users To level-up the security of your users and ensure the usage of the SSO integration, you can enforce Multi-Factor Authentication (MFA) for all users and require them to log in using the Azure Entra ID SSO. ### SSO Route Create a dedicated route for your users to log in to Breeze using the Azure Entra ID SSO. This route will redirect users to the Azure Entra ID login page, where they can log in using their organization's credentials. To learn more about the SSO route, see [SSO Route](#sso-route). ### SSO User Onboarding Automatically create new users when logging in from an SSO source if they do not already exist in Breeze. This feature streamlines the process of adding new users to Breeze and ensures that all users have access to the platform. For more information, see [SSO User Onboarding](#sso-user-onboarding). ### SSO Role Management Simplify the assignment and management of user roles by using the SSO Role Management feature. This feature allows you to assign roles to users based on their Azure Entra ID group membership. For more information, see [SSO Role Management](#sso-role-management). --- ## SSO User Onboarding ## Introduction Single Sign-On (SSO) User Onboarding in Breeze allows you to automatically create and manage users based on their identity provider (IdP) credentials. This ensures a seamless login experience and simplifies user management by leveraging existing identity systems. This guide provides instructions on how to configure SSO User Onboarding in Breeze. ## Prerequisites Before setting up SSO User Onboarding, ensure that an SSO integration is already set up in Breeze. For more information on setting up SSO, refer to the [Setup Azure AD/ Entra ID](docs/authentication/sso/sso-setup-azure-ad.md). :::warning Any changes performed in the SSO User Onboarding configuration will take immediate effect. Ensure that you have tested the configuration in a non-production environment before applying it to a production environment. Consider communicating with your users before making changes to the SSO User Onboarding configuration to avoid any disruptions. ::: ## Configuration ### Default Configuration By default, the user onboarding configuration is set to "none." This means that users from the IdP will not be accepted or created in Breeze unless they are already manually created in Breeze with the same email as registered in the IdP. ### Enabling Automatic User Onboarding To enable automatic user onboarding, the following steps are required: 1. **Navigate to Tenant Settings**: In the Breeze admin portal, go to the `Tenant settings` page. 2. **Open Security Settings**: Select the `Security settings` tab and click on `Edit security settings`. 3. **Configure SSO Settings**: In the `SSO Settings` section, click the `Change Settings` button. 4. **Locate** the `User Onboarding` section and click on the `Change Settings` button. 5. **Change** the `SSO User Onboarding Type` setting to `Create users`. 6. **Configure** as needed, see more details below. ### Static Mapping In static mapping, all users are assigned to a single tenant. This is the simplest form of mapping and is what most Tenants will use. Simply set the `Mapping Type` to `static` and select the `Tenant` to which all users will be assigned. Once a new user logs in via SSO, they will be created in the selected tenant. #### Settings details | Setting | Description | |---------------------------------------------------------------------|-------------| | **Mapping Type** | Set to `Static` | | [**Allow only one active account**](#allow-only-one-active-account) | Check this box to allow only one active account per user. | | **Tenant** | The tenant ID to which all users will be assigned. Dropdown with a list of available tenants. | ### Dynamic Mapping In dynamic mapping, users are assigned to tenants based on specific attributes in the IdP response. This allows for more granular control over user onboarding and tenant assignment. #### Settings details | Setting | Description | |---------------------------------------------------------------------|-------------| | **Mapping Type** | Set to `Dynamic`. | | [**Allow only one active account**](#allow-only-one-active-account) | Check this box to allow only one active account per user. | | [**Dynamic SSO Field**](#dynamic-sso-field) | The field in the IdP response that contains the value used to map the user to a tenant. | | [**Dynamic Values**](#dynamic-values) | A list of mappings that define which tenant corresponds to which IdP field value. | | [**Dynamic SSO Fallback**](#dynamic-sso-fallback) | The fallback tenant ID if no dynamic mapping is found. | #### Dynamic SSO Field The `Dynamic SSO Field` setting specifies the field in the IdP response that contains the value used to map the user to a tenant. This field must be present in the IdP response in order to map users to tenants dynamically. For example, if the IdP response contains a field called `department` that specifies the user's department, you would set the `Dynamic SSO Field` to `department`. :::note If this field is not present in the IdP response, the user will be assigned to the fallback tenant. ::: #### Dynamic Values The `Dynamic Values` setting allows you to define mappings that specify which tenant corresponds to which IdP field value. To add multiple mappings, click the `Add Mapping` button and enter the IdP field value and the corresponding tenant ID. Breeze will then parse the IdP response and assign the user to the tenant that corresponds to the value in the specified field. For example, if the `department` field in the IdP response contains the value `Oslo`, you would create a mapping that assigns users with the `Oslo` department to the `Norway` tenant. :::note If the IdP response contains a value that does not have a corresponding mapping, the user will be assigned to the fallback tenant. ::: #### Dynamic SSO Fallback The `Dynamic SSO Fallback` setting specifies the tenant ID to which users will be assigned if no dynamic mapping is found or if the `Dynamic SSO Field` is not present in the IdP response. #### Allow only one active account Check this box to allow only one active account per user. If a user is already active on a different tenant under the same SSO Auth profile, they will be deactivated before the new user is activated/created. This may happen if the SSO is set up with a dynamic tenant mapping, or if the static tenant has changed since the user was created. This setting is available for both `Static` and `Dynamic` mapping types. ## Roles Once a user is created in Breeze, they will be assigned a set of roles based on the configuration in the `Role Management` section. By default all users will be assigned the `User` role, but you can configure this to assign different roles or even set up dynamic role assignment based on the user's IdP attributes. For more information on role management, refer to the [Role Management](docs/authentication/sso/sso-role-management.md) guide. --- ## Credential Statuses Credential statuses show where a credential is in its journey from creation to activation. This page explains what each status means and when you'll see it. ## Status Overview Credential statuses fall into these main stages: - **Preparation**: Being created and edited - **Approval**: Waiting for review (if your policy requires it) - **Production**: Being made or issued - **Active Use**: Ready and in use - **Deactivated**: Temporarily turned off - **End of Life**: Replaced, cancelled, or deleted ## Preparation Statuses These statuses show credentials that are being prepared before production. ### Registered **Just created. Being prepared. Not submitted for ordering yet.** - **How it gets here**: A new Credential is started - **What happens next**: You can move it to preview, requested, waiting_for_approval (if approval is needed), or in_queue (in fast-track setups) - **Can it move forward?** Yes - **Notes**: This is a safe place to edit details and photos before submitting ### Preview **A visual preview exists (e.g., card front/back). Still in preparation.** - **How it gets here**: You generated a preview while preparing the Credential - **What happens next**: You can move it to requested, waiting_for_approval, or in_queue - **Can it move forward?** Yes - **Notes**: Use this to catch mistakes before ordering or issuing ### Requested **Submitted for ordering. Added to the shopping cart when using the standard flow.** - **How it gets here**: You submit the Credential for ordering - **What happens next**: After checkout it moves to in_order, or to waiting_for_approval if an approver must sign off first - **Can it move forward?** Yes - **Notes**: This is the "I'm ready—put me in the order" step ## Approval Statuses These statuses show credentials waiting for approval. ### Waiting for Approval **Needs an approver to review before it can move forward.** - **How it gets here**: Your policy requires approval for this Credential - **What happens next**: After approval, it moves to in_queue (fast-track flows) or requested (standard flow). If not approved, it may be cancelled - **Can it move forward?** Yes (after approval) - **Notes**: Approvers see what they need to approve; nothing moves until they decide ## Production Statuses These statuses show credentials being made or issued. ### In Queue **Approved (or no approval needed) and queued to start preparation.** - **How it gets here**: Approved (or auto-approved) and placed in the queue - **What happens next**: Moves to in_production (cards) or straight to active/inactive for some mobile setups - **Can it move forward?** Yes - **Notes**: Some tenants start automatic preparation from here ### In Order **Placed in an order. Waiting for production (for cards) or for mobile handling.** - **How it gets here**: The order has been placed/checked out - **What happens next**: Moves to in_production (cards) or active/inactive (mobile IDs with automatic handling) - **Can it move forward?** Yes - **Notes**: Batches appear here too; each Credential still has its own progress ### In Production **Being made. For cards: printing/encoding is in progress. For mobile IDs: this state is brief and will quickly move forward automatically.** - **How it gets here**: Production has started - **What happens next**: Moves to quality_check (cards) or active/inactive (mobile) - **Can it move forward?** Yes - **Notes**: For mobile, this can be a quick hop; for cards, this covers the making/encoding step ### Quality Check **Finished making and awaiting a final review.** - **How it gets here**: Card production completed and is awaiting a final check - **What happens next**: If approved, moves to produced. If not approved, goes back to in_production for rework - **Can it move forward?** Yes (after approval) - **Notes**: Use this step to ensure photos, text, and encoding are correct ### Produced **Fully made and approved. Ready for handout or activation.** - **How it gets here**: Passed quality check or completed production in a fast-track setup - **What happens next**: Moves to active (put into use), in_production (rework), or deleted (if removed) - **Can it move forward?** Yes - **Notes**: For cards, you can now hand out; for mobile, next is typically activation ## Active Use Statuses These statuses show credentials that are ready to use or in use. ### Active **Ready and in use. The credential works wherever it's connected (e.g., access control or Mobile ID).** - **How it gets here**: Activated after being produced/issued - **What happens next**: Can move to deactivated, replaced, or deleted (depending on policy) - **Can it move forward?** Yes - **Notes**: This is the normal "live" state ### Inactive **Mainly for mobile IDs. Prepared but not yet turned on (manual provisioning required before use).** - **How it gets here**: A mobile ID is prepared but not activated automatically - **What happens next**: Can move to active or deactivated - **Can it move forward?** Yes - **Notes**: Common for manual provisioning flows ### Deactivated **Temporarily turned off. Can be re‑activated later when appropriate.** - **How it gets here**: You turned off a live Credential (lost card, leave of absence, etc.) - **What happens next**: Can move to active (restore), replaced, or deleted - **Can it move forward?** Yes - **Notes**: Use when you don't want to remove it permanently ## End of Life Statuses These statuses show credentials that are no longer in active use. ### Replaced **An older credential has been superseded by a new one. Kept for history, no longer the one in use.** - **How it gets here**: A new Credential was created to supersede this one - **What happens next**: Typically stays replaced; may later be deleted based on retention rules - **Can it move forward?** Effectively no (for operational use) - **Notes**: Keeps a clean history of what changed and when ### Cancelled **Stopped before production. Often means it was removed from an order/cart and won't be made.** - **How it gets here**: The order item was removed or the request was withdrawn - **What happens next**: Usually stays cancelled; you can create a new Credential if needed - **Can it move forward?** Usually no - **Notes**: Prevents unwanted production ### Deleted **Permanently removed. Personal details are anonymized and the credential is no longer available.** - **How it gets here**: An admin deleted the Credential - **What happens next**: Nowhere - **Can it move forward?** No - **Notes**: This is permanent; used for cleanup or compliance ## Duo ID Statuses These statuses show credentials where a Duo ID invite was sent so the person can provide their own details. ### Duo Requested **A Duo ID invite was created and (optionally) emailed so the person can supply details (like a photo).** - **How it gets here**: You start a Duo ID invite for the person to complete details - **What happens next**: After the person submits, moves to duo_waiting_for_approval, or duo_rejected if the attempt is ended - **Can it move forward?** Yes - **Notes**: You can resend the invite if needed ### Duo Waiting for Approval **The person has sent in their details. Waiting for an approver to review.** - **How it gets here**: The invited person submitted their information - **What happens next**: After approval, moves to requested or in_queue (depending on your flow), or duo_rejected if rejected - **Can it move forward?** Yes (after approval) - **Notes**: After approval, it continues like any other Credential ### Duo Approved **Not commonly used in today's flow. After approval, credentials typically move straight into "requested" or "in_queue".** - **How it gets here**: Legacy paths may mark "approved" - **What happens next**: Moves to requested or in_queue - **Can it move forward?** Yes - **Notes**: Most tenants skip this explicit status today ### Duo Rejected **The submission was rejected. If needed, a new invite can be sent with corrections.** - **How it gets here**: The approver rejected the submission - **What happens next**: Can move to duo_requested (if you send a fresh invite), or it can remain rejected - **Can it move forward?** Usually no, unless you retry - **Notes**: Capture the reason; it helps when resending ## Rare or Legacy Statuses These statuses are rarely used in current workflows but may appear in special cases. ### Soft Deleted **Not commonly used for credentials. Reserved for special cases where items are hidden but kept.** - **How it gets here**: Rare internal flows - **What happens next**: Can move to deleted - **Can it move forward?** No (but it's close to end‑of‑life) - **Notes**: Not visible in normal daily lists ### Rejected **Rarely used for credentials in the current flow. Kept for compatibility with earlier processes.** - **How it gets here**: Legacy or special handling - **What happens next**: Can move to replaced or deleted (depending on policy), or remain rejected - **Can it move forward?** Usually no in practice - **Notes**: Newer flows typically use approval/cancel paths instead ## Understanding Status Flow Credentials move through statuses in a logical flow, but the exact path depends on: - **Your policy settings**: Whether approval is required - **Credential type**: Cards vs. mobile IDs follow slightly different paths - **Workflow setup**: Fast-track vs. standard flows - **Quality checks**: Whether rework is needed Most credentials follow a path like: 1. **Registered** → (optional) **Preview** 2. **Requested** → (optional) **Waiting for Approval** 3. **In Order** → **In Production** → (cards) **Quality Check** 4. **Produced** → **Active** ## Common Questions ### Why is my credential stuck in one status? - Check if approval is required and waiting - Verify the credential hasn't been cancelled or rejected - For mobile IDs, check if manual provisioning is needed ### Can I skip some statuses? Some fast-track setups may skip certain statuses (like approval or quality check), but most credentials follow the standard flow. ### What's the difference between deactivated and deleted? - **Deactivated**: Temporarily turned off; can be reactivated later - **Deleted**: Permanently removed; cannot be recovered ## Related Documentation - **[Credential Management Overview](/docs/credential-management/)** — Learn about credentials and what you can do with them - **[Understanding Mobile Credential Lifecycle](/docs/credential-management/mobile-credentials-lifecycle)** — Detailed lifecycle information - **[Using List View](/docs/credential-management/using-list-view)** — Work with credential lists and manage credentials --- ## Customizing the Credentials List This guide explains how tenant administrators can customize the credentials list view for their organization. :::note[Required Roles] **Required roles**: `Tenant Administrator`, `User Administration` To customize the credentials list view, you need to have both roles listed above. ::: ## Prerequisites Before you begin, ensure you have: - Access to the Manage Credentials section - A web browser with an active Breeze session ## Customization Process ### 1. Access List Settings 1. Navigate to the `Manage Credentials` section 2. Click the "Customize List" button in the action bar above the credentials list 3. The Customize Credentials List dialog will open ![Customize List Button Location](./_images/customize-list-button.png) ### 2. Select Fields In the left panel, you'll see all available fields grouped into categories. Some examples of fields include: - **Credential Fields** - Credential Number - Status - Creation Date - Other basic credential information - **Template Fields** - Template Name - Template-specific information - **Order Fields** - Order Number - Order-related information - **Tenant Fields** (useful when using Domain View) - Tenant ID - Tenant Name To select fields: 1. Browse through the categories 2. Check the boxes next to fields you want to display 3. Hover over field names to see descriptions ![Field Selection Panel](./_images/field-selection-panel.png) ### 3. Arrange Fields In the right panel, you can organize the selected fields: 1. Use the handle icon (≡) on the left of each field to drag 2. Drag and drop fields to change their order 3. The order here determines how columns appear in the list ![Field Arrangement Panel](./_images/field-arrangement-panel.png) ### 4. Configure Field Properties For each selected field, you can configure: - **Sortable**: Allows users to sort the list by this field - **Filterable**: Allows users to filter credentials using this field Use the switches next to each field to enable or disable these features. ### 5. Save Changes 1. Review your configuration 2. Click "Save" to apply your changes 3. The new configuration will be immediately available to all users 4. Click "Cancel" to discard changes ## Best Practices ### Field Selection - Choose fields that are most relevant to your users' daily tasks - Avoid selecting too many fields to prevent information overload (recommended: 8-12 fields) - Include fields commonly used for sorting and filtering - Consider the logical grouping of information - **For main Tenants using Domain View**: Include "Tenant - Name" or "Tenant ID" fields to help users identify which Tenant each Credential belongs to when viewing domain-wide results ### Field Ordering - Place most frequently used fields on the left - Group related fields together (e.g., keep all date fields adjacent) - Consider the natural workflow of your users - Put optional or less-used fields towards the right ### Configuration Management - Test the configuration with different screen sizes - Gather feedback from users about field visibility and ordering - Periodically review and update the configuration (quarterly recommended) - Document your configuration decisions for future reference ## Technical Considerations ### Performance - More visible fields may impact loading performance - Consider the impact of enabling sorting/filtering on all fields - Balance between functionality and performance ### User Experience - Changes affect all users in the tenant - New configurations apply immediately - Users may need to refresh their browser - Consider providing user training for significant changes - Plan communication before making major layout changes ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | ---------------------- | ----------------------- | -------------------------------------------------- | | Changes don't appear | Browser cache | Ask users to refresh their browser | | Sorting doesn't work | Field not sortable | Verify sortable property is enabled for the field | | Filtering doesn't work | Field not filterable | Check filterable property is enabled for the field | | Performance issues | Too many visible fields | Reduce the number of visible fields | | List appears cluttered | Too many columns | Prioritize essential fields only | ### Getting Help If you encounter issues: 1. Check that you have the required roles 2. Verify your changes were saved successfully 3. Take a screenshot of the issue if possible 4. Contact support if problems persist, providing details about: - The specific action you were taking - Any error messages displayed - The browser and version you're using --- ## Customizable Credentials List ## Overview The Customizable Credentials List feature empowers tenant administrators to create tailored views of credential information, making it easier for their teams to find and manage credentials efficiently. This feature addresses the common challenge of information overload by allowing organizations to display only the most relevant credential information for their specific needs. :::note[Required Roles] **Required roles**: `Tenant Administrator` AND `User Administration` To customize the credentials list view, you need to have both roles listed above. ::: ## Key Features ### Field Customization - **Selective Display**: Choose which credential fields are visible in the list view - **Custom Ordering**: Arrange fields in the most logical order for your workflow - **Tenant-Level Settings**: Save customized view configurations at the tenant level - **Default Reset**: Restore standard view when needed ### Smart Field Categories Available field types include: | Category | Description | Example Fields | |----------|-------------|----------------| | **Credential Information** | Basic credential details | ID, Status, Creation Date, Expiration Date | | **Template Details** | Information about the credential template | Template Name, Type, Version | | **Order Information** | Related order details | Order Number, Status, Date, Requester | ### Advanced List Management - **Dynamic Sorting**: Sort by any visible column with a single click - **Custom Filtering**: Filter credentials based on displayed fields - **Pagination Controls**: Navigate through large sets of credentials easily - **Bulk Operations**: Perform actions on multiple selected credentials simultaneously ## Business Benefits ### Improved Efficiency - Reduced search time with focused views - Streamlined workflows matching specific business processes - Faster training for new users with relevant information only - Efficient bulk operations for common credential management tasks ### Better Data Organization - Display only necessary information for your organization's needs - Maintain consistent layouts across the tenant - Adapt to changing business needs with quick configuration updates - Optimize display based on usage patterns and user feedback ### Enhanced User Experience - Reduced complexity with relevant fields only - Faster loading with optimized data retrieval - Intuitive navigation with logical field ordering - Consistent interface across the organization ## Technical Considerations :::warning Changes to the list configuration affect all users in your tenant. Consider gathering feedback from your team before making significant changes. ::: - Configuration changes apply immediately to all users in the tenant - Users may need to refresh their browsers to see changes - Performance may be impacted by the number of visible fields - Large credential databases benefit most from optimized views ## Next Steps - [Administrator Guide](./administrator-guide) - Learn how to customize the credentials list for your tenant - [Using the List View](/docs/credential-management/using-list-view) - Learn how to effectively use the credentials list - [Data Export Guide](/docs/credential-management/data-export) - Learn how to export credential data --- ## Exporting Credential Data ## Overview The credential data export feature allows authorized users to download credential data in Excel format. This functionality is designed for reporting, analysis, and backup purposes, with built-in controls to ensure data security and proper handling. :::note[Required Roles] **Required roles**: `Super Admin` AND `Data Exporter` To perform the following steps, you need to have both roles listed above. ::: ## Export Features ### Data Format - Files are exported in Excel (.xlsx) format - File naming convention: `Credentials-[TenantName]_[Date]` - All available credential fields are included - Data is properly formatted based on field types (dates, numbers, text) ### Export Scope - Export all credentials matching your current filters - Option to export complete credential database - Large exports can be broken down using filters - Real-time data export (reflects current state at export time) ## Export Process ### 1. Prepare Your Export 1. Navigate to the credentials list view 2. Apply desired filters to select specific data 3. Verify the filtered results match your needs ### 2. Initiate Export 1. Click the "Export Search Results" button in the action bar 2. Wait for the export generation (indicated by a progress indicator) 3. Download will start automatically when ready 4. Files are not stored on the server after download completes ![Export Button Location](./_images/export-button.png) ### 3. Working with Export Files - Open the Excel file in your preferred spreadsheet application - Data is organized by columns matching credential fields - All data is formatted appropriately for its type - Column headers match the field names in the Breeze platform ## Best Practices ### Data Selection - Use filters to export specific subsets of data - Consider breaking large exports into smaller chunks by: - Filtering by date ranges - Filtering by status types - Filtering by template types - Verify filter criteria before exporting - Clear filters if you need the complete dataset ### File Management - Save exports with meaningful names (e.g., `Active-Credentials-Q2-2023.xlsx`) - Store exports securely according to your data classification policies - Delete old exports when no longer needed - Consider compression for large files to save storage space ### Performance Considerations - Large exports (>10,000 records) may take longer to generate - Filter data before export when possible - Avoid exporting during peak usage times (typically business hours) - Consider scheduling large exports during off-hours ## Security and Compliance :::warning Exported data may contain sensitive information. Always follow your organization's security policies when handling exported files. ::: ### Access Control - Role-based access control ensures only authorized users can export - Audit logging of all exports (who, when, how many records) - Downloads are tracked and logged for compliance purposes ### Data Protection - Exports contain sensitive information that requires protection - Handle exported files according to your security policies - Consider encryption for stored export files - Limit distribution of exported data to authorized personnel only ## Troubleshooting ### Common Issues | Issue | Possible Causes | Solutions | | ----------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Export Button Not Visible** | Missing required rolesIncorrect navigation | Verify you have both required rolesCheck with your administratorEnsure you're in the credentials list view | | **Export Taking Too Long** | Large data setNetwork issuesServer load | Reduce the amount of data using filtersTry during off-peak hoursCheck your network connection | | **File Format Issues** | Software compatibilityFile corruption | Ensure you have compatible spreadsheet softwareTry re-downloading the fileUse a different browser | ### Getting Help If you encounter issues: 1. Verify your roles and permissions 2. Contact your system administrator with the following details: - The specific action you were attempting - Number of records you were trying to export - Any error messages displayed 3. Reach out to support if needed ## Related Topics - [Using the List View](/docs/credential-management/using-list-view) - [Filtering Credentials](/docs/credential-management/using-list-view#find-credentials-fast-filtering) - [Customizing the List View](/docs/credential-management/customizable-list) --- ## Email History The Email History dialog shows you all emails sent by Breeze for a Credential and their delivery status. This includes emails like Duo ID invites, notifications, and any other Breeze-generated emails related to the Credential. **Important:** This dialog only shows emails sent directly by Breeze. Emails sent by third-party services (like Mobile ID issuance emails from the STid provider) are not included here, as Breeze doesn't control or track those. The dialog is perfect for checking whether emails like Duo ID invites were delivered, seeing when emails were sent, and understanding what happened if an email didn't reach its recipient. Think of it as your email delivery audit trail—you can see exactly what was sent by Breeze, when it was sent, and whether it successfully reached the recipient. :::note[Required Roles] **Required roles**: `Admin` To perform the following steps, you need to have both roles listed above. ::: ## Opening Email History To view email history for a Credential: 1. Navigate to the Credential details page 2. Look for the **"View Email History"** button in the action buttons section - This button only appears when there are emails associated with the Credential - If you don't see the button, no emails have been sent for this Credential yet 3. Click **"View Email History"** to open the dialog 4. The dialog opens showing all emails sent for this Credential, with the most recent email automatically selected ## Understanding the Email List The dialog shows a list of all emails sent by Breeze for the Credential (currently this mainly includes Duo ID invites, but the dialog is designed to show any Breeze-generated emails related to Credentials). The layout is split into two sections: - **Left side**: List of all emails (up to 100 most recent) - **Right side**: Detailed information for the selected email When the dialog first opens, the newest email is automatically selected so you can immediately see the latest email details. Each email in the list shows: - **Email Type** — What kind of email it was (e.g., "Duo ID") - **Status** — Current delivery status with a visual indicator badge - **Recipient** — The email address it was sent to - **Date and Time** — When the email was sent Emails are listed chronologically, with the most recent at the top. Click any email in the list to see its full details on the right. ## Viewing Email Details Click any email in the list to see detailed information about that specific email. The details panel shows: ### Email Information - **Email Type** — The type of email (e.g., Duo ID invite) - **Status** — Current delivery status with visual indicator - **To** — Recipient email address - **Subject** — The email subject line - **Sent** — Exact date and time when the email was sent ### Timeline The Timeline section shows the email's complete journey with event progression in reverse chronological order (most recent first). Here's what you'll see: **Successful email flow:** - **Sent** — When Breeze sent the email to the email provider - **Delivered** — When the email successfully reached the recipient's mailbox - **Opened** — When the recipient opened the email (if tracking is available) - **Clicked** — When the recipient clicked a link in the email (if tracking is available) **Failed email flow:** - **Soft Bounce - Temporary Issue** — Email couldn't be delivered temporarily (e.g., inbox full, server unavailable). The provider may retry. - **Hard Bounce - Invalid Address** — Email couldn't be delivered permanently (invalid address, domain doesn't exist). This is a permanent failure. - **Marked as Spam** — Recipient marked the email as spam (**Note** that emails might have been delivered to the recipient's spam folder even though it is not marked as spam here) - **Blocked** — Email was blocked before delivery - **Delivery Failed** — Generic failure status for various errors The timeline shows exactly what happened and when, giving you a complete picture of the email's lifecycle from sending through delivery and (if applicable) being opened or clicked. Here's an example of a complete successful email timeline showing all stages: ## Email Statuses Explained Each email has a **status** (final delivery state) and a **timeline** (history of events). The status shows the final delivery outcome (like "Delivered" or "Hard Bounce"), while the timeline shows the complete journey including engagement events like "Opened" and "Clicked" that don't change the status. ### Active Statuses (Can Change) These statuses can change as the email progresses: - **Queued** — Email is waiting to be sent (you'll rarely see this) - **Sent** — Email was successfully sent from Breeze to the email provider. The email is now in transit, but we don't yet know if it reached the recipient's inbox. - **Soft Bounce - Temporary Issue** — Email couldn't be delivered temporarily (e.g., recipient's inbox is full, server temporarily unavailable). The provider may retry automatically. This is usually not permanent. ### Terminal Statuses (Final State) These statuses are final—the email won't progress beyond these. Once an email reaches a terminal status, that's where it stays: - **Delivered** — Email successfully reached the recipient's inbox. This is the best outcome! Once delivered, the status stops updating. However, you'll still see additional events in the timeline (like "Opened" or "Clicked") that show engagement, but these don't change the status from "Delivered." - **Hard Bounce - Invalid Address** — Email couldn't be delivered permanently because: - The email address was typed incorrectly - The domain doesn't exist - The mailbox has been deleted If you see this, verify and correct the email address on the Credential, then resend the email. - **Marked as Spam** — Recipient marked the email as spam. The email was likely delivered but moved to spam folder. **Note** that emails might have been delivered to the recipient's spam folder even though it is not marked as spam here. - **Blocked** — Email was blocked before delivery (e.g., recipient's email server blocked it, or email address is on a blocklist). - **Invalid Email Address** — Email address is invalid or malformed. The email cannot be sent. - **Delivery Failed** — Generic failure status that can appear for various errors including: - System errors - Provider errors - Temporary server issues - Unsubscribe status Check the timeline for more specific error details. **Note about engagement events:** While "Opened" and "Clicked" appear in the timeline (and are great for seeing if recipients engaged with e.g. Duo ID invites), these are events, not statuses. The email status will remain "Delivered" even when these engagement events are logged. ## Common Use Cases ### Checking Email Delivery Status When Breeze sends an email for a Credential (like a Duo ID invite), check the Email History to confirm it was delivered and opened: 1. Look for the email in the list — it should show "Delivered" status 2. Click it to see the timeline 3. Check if there's an "Opened" event — this confirms the recipient actually viewed the email 4. For the best engagement, look for a "Clicked" event, which means they interacted with links in the email If you see a bounce or error status, verify the email address is correct and resend the email. **Note:** If you're looking for Mobile ID issuance emails (sent by the STid provider), those won't appear here. This dialog only shows emails sent directly by Breeze. ### Troubleshooting Missing Emails If someone says they didn't receive an email, open Email History to see: - Was the email actually sent? - What was the delivery status? - When was it sent? This helps you determine if the issue is on your side (wrong email address, bounce) or if the email was delivered but the recipient didn't see it (spam folder, etc.). ### Why Aren't Mobile ID Issuance Emails Shown Here? If you're looking for emails sent when a Mobile ID Credential is issued (like activation emails from STid), you won't find them in this dialog. **Reason:** Mobile ID issuance emails are sent directly by the STid provider service, not by Breeze. Since Breeze doesn't control or have visibility into those third-party email services, those emails can't be tracked here. **What you'll see instead:** This dialog only shows emails sent directly by Breeze, such as Duo ID invites and other Breeze-generated notifications. For Mobile ID issuance emails, you'd need to check with the STid provider directly or consult their documentation for email delivery tracking. ### Verifying Email Timestamps The timeline shows exact timestamps for each stage of email delivery, which can be useful for: - Understanding delivery delays - Documenting when emails were sent for audit purposes - Troubleshooting time-sensitive communications ## Important Notes - **Breeze emails only** — This dialog only shows emails sent directly by Breeze. Emails from third-party services (like Mobile ID issuance emails from STid provider) are not tracked here, as Breeze doesn't control those email services. - **All Credential-related emails** — The dialog displays all Breeze-generated emails for the Credential. Currently, this primarily includes Duo ID invites, but the dialog is designed to show any emails Breeze sends related to Credentials. - **Most recent emails only** — The dialog shows up to the 100 most recent emails for the Credential. Older emails beyond this limit won't appear. - **Email retention** — Emails are retained for 365 days. After this period, older emails will automatically be deleted. - **Feature introduction date** — This feature was introduced on November 3, 2025. No emails were logged or tracked prior to this date, so you won't see any email history for emails sent before then. - **Button visibility** — The "View Email History" button only appears when there are Breeze emails associated with the Credential. If you don't see it, no Breeze emails have been sent yet. - **Email content privacy** — Email History shows email metadata (who, when, subject, status) but never shows the actual email body or content for privacy reasons. Emails are deleted after 365 days. - **Status updates** — Delivery statuses reflect the most current information from the email delivery service. Some statuses like "Delivered" or "Opened" may take a few moments to update after the email is sent. - **Automatic selection** — When you open the dialog, the newest email is automatically selected so you can immediately see the latest activity. ## Closing the Dialog Click **"Close"** or press **ESC** to dismiss the Email History dialog and return to the Credential details page. ## Related Documentation - **[Mobile Credential Lifecycle](./mobile-credentials-lifecycle)** — Understand Credential states and transitions - **[Credential Statuses](./credential-statuses)** — Learn about different Credential statuses - **[Using List View](./using-list-view)** — Manage Credentials from the list view --- ## External Data Lookup External Data Lookup allows you to automatically retrieve person information from external systems when ordering Credentials. Instead of manually entering person details, you can enter a search identifier and let the system populate Credential fields automatically. ## Overview When a Credential Template is configured with an external data source, you can use external data lookup during Credential ordering to: - **Automate data entry** — Retrieve person data automatically from authoritative sources - **Improve accuracy** — Reduce manual input errors by pulling data directly from external systems - **Speed up ordering** — Pre-fill Credential fields with verified person information - **Support compliance** — Use data from official registries like Norwegian Folkeregisteret ### Supported external data sources Breeze supports the following external data sources for person lookup: - **Norwegian Folkeregisteret (FREG)** — Norwegian National Registry for person data lookup - **SPAR** — Swedish population register - **Breeze ID Connector** — A generic connector for your own OAuth-protected person lookup API :::note[Prerequisites] To use external data lookup: - The Credential Template you're using must be configured with an external data source - You must have permission to order Credentials using that template ::: ## How external data lookup works The lookup process is the same regardless of which external data source your template uses: 1. **Select a template** — Choose a Credential Template that has been configured with an external data source 2. **Enter search identifier** — Enter the identifier required by your external data source (see source-specific requirements below) 3. **Run the lookup** — Click **"Search"** to retrieve person data from the external system 4. **Review populated data** — If the lookup is successful and a match was found, Credential fields are automatically filled with data from the external source 5. **Complete the order** — Review the populated data, fill in any remaining fields, and submit the Credential for ordering If the lookup fails, you can typically continue by entering the information manually. ## Source-specific requirements Each external data source has specific requirements for search identifiers and may have different authentication or availability constraints. ### Norwegian Folkeregisteret (FREG) **Availability**: Only available if your organization has FREG configured as an external data source **Input format**: Enter an 11-digit Norwegian personal identity number (exactly 11 digits, no spaces, dashes, or other characters) **Authentication**: Level 4 authentication (BankID) may be required for natural person lookups **For configuration**: See [External Data Sources](/docs/domain-administration/external-data-sources) for how to configure FREG as an external data source ### SPAR (Sweden) **Availability**: Only available if your organization has SPAR configured as an external data source **Input format**: Enter a Swedish personal number in the format YYYYMMDDNNNN (12 digits total). The format is: - **Year**: 4 digits (19xx or 20xx) - **Month**: 2 digits (01-12) - **Day**: 2 digits (01-31) - **Last 4 digits**: Any 4 digits You can optionally include a dash (e.g., YYYYMMDD-NNNN), which will be automatically removed during validation. **Authentication**: Level 4 authentication (BankID) is required for natural person lookups **For configuration**: See [External Data Sources](/docs/domain-administration/external-data-sources) for how to configure SPAR as an external data source ### Breeze ID Connector **Input format**: Enter the identifier or search value your organization uses for the connected external service **Response format requirement**: The connected service must return person data in a **specific Breeze format** (it's not compatible with arbitrary API responses). At minimum, the response must include an `identifier` field. :::note[Response format requirement] Breeze ID Connector requires the connected service to return person data in a **specific Breeze format** (it's not compatible with arbitrary API responses). If the external service doesn't return the expected format, the lookup will fail. **Reach out to Breeze support**—we can provide the expected response format and guidance for mapping. ::: **Common errors**: - Person not found: "Identifier had no match" - Invalid response format: Lookup fails if the external service doesn't return the expected format **Solution**: Verify the search identifier is correct, or contact Breeze support for response format requirements **For configuration**: See [External Data Sources](/docs/domain-administration/external-data-sources) for how to configure Breeze ID Connector as an external data source ## How to use external data lookup ### Step 1: Start Credential ordering 1. Navigate to the Credential ordering page 2. Select a Mobile Credential Template that has been configured with an external data source ### Step 2: Enter search identifier 1. In the **Credential Data** section, you'll see an external data lookup form 2. Enter the search identifier in the **"Search identifier"** field (see [Source-specific requirements](#source-specific-requirements) above for format details) 3. Click **"Search"** or press Enter ### Step 3: Review populated data 1. If the lookup is successful, you'll see a **"Lookup performed successfully!"** message 2. Credential fields are automatically populated with data from the external system, for example: - **Firstname** — Automatically filled from external data source - **Lastname** — Automatically filled from external data source - Other mapped fields — Populated according to template configuration 3. Fields populated from external data are typically locked (disabled) to prevent accidental changes 4. Review the populated data to ensure it's correct ### Step 4: Complete Credential information 1. Fill in any remaining Credential fields that weren't populated by the lookup 2. Upload or provide a photo if required 3. Review all information before submitting 4. Submit the Credential for ordering ### Step 5: Redo lookup (if needed) If you need to perform a new lookup with a different search identifier: 1. Click **"Redo lookup"** to clear the current lookup results 2. Enter a new search identifier 3. Click **"Search"** again ## Handling errors ### Invalid search identifier format **Applies to**: FREG, SPAR (and other sources with strict format requirements) If you enter an incorrectly formatted search identifier, you'll see an error message: - **For FREG**: "Invalid search string, must be 11 digits (Norwegian personal identity number)" - **Solution**: Enter exactly 11 digits (no spaces, dashes, or other characters) - **For SPAR**: "Invalid personal number" (or similar validation error) - **Solution**: Enter a Swedish personal number in YYYYMMDDNNNN format (12 digits total, optionally with a dash) ### Person not found **Applies to**: All external data sources If the search identifier doesn't match any person in the external system: - Error message: "Person not found" or "Identifier had no match" - **Solution**: Verify the search identifier is correct and try again, or enter person data manually ### Authentication required **Applies to**: FREG, SPAR (and other sources that require authentication) Some external data sources require Level 4 authentication (BankID) for natural person lookups: - **FREG**: Level 4 authentication (BankID) may be required - **SPAR**: Level 4 authentication (BankID) is required - You'll be prompted to authenticate using BankID - Complete the authentication process to proceed with the lookup ### Manual entry fallback If external data lookup fails for any reason, you can still enter person data manually to complete the Credential order. ## Limitations and considerations - **Format requirements**: Each external data source has specific format requirements for search identifiers: - **FREG**: Exactly 11 digits (Norwegian personal identity number) - **SPAR**: YYYYMMDDNNNN format (12 digits, Swedish personal number) - **Breeze ID Connector**: Depends on your organization's external service requirements - **Authentication**: Some lookups require Level 4 authentication (BankID) - FREG and SPAR both require this for natural person lookups - **Rate limiting**: External data sources may have rate limits that apply to lookups - **Data availability**: Person data must exist in the external system for the lookup to succeed - **Field mapping**: Only fields configured in the template's field mappings will be populated - **Response format** (Breeze ID Connector): The external service must return data in Breeze's expected format - **Configuration**: External data sources must be configured by administrators before they can be used - see [External Data Sources](/docs/domain-administration/external-data-sources) for setup instructions ## Tips for best results - **Verify identifiers**: Double-check search identifiers before entering them to avoid errors - **Use official sources**: When possible, use identifiers from official documents or systems - **Review populated data**: Always review automatically populated data to ensure accuracy - **Manual entry fallback**: If lookup fails, you can still enter person data manually ## Learn more - **[External Data Sources](/docs/domain-administration/external-data-sources)** — Configure external data sources in Domain Administration - **[Editing Templates](/docs/template-management/mobile-credential-templates/editing-templates)** — Configure templates with external data source connections - **[Mobile Credential Templates](/docs/template-management/mobile-credential-templates/)** — Overview of template management - **[Credential Management](/docs/credential-management/)** — Overview of credential management features --- ## ID Photo Requirements Your Credential photo must meet these requirements to be approved and used on your ID. Photos that don't meet these standards may be rejected, which can delay the Credential creation process. High-quality images are essential for clear identification and professional appearance. Your photo must be sharp, in focus, and have good contrast so your face is clearly recognizable. Blurry, pixelated, or poorly lit photos won't meet the standards required for official credentials. Use a passport-style photo with good lighting and a plain background. The examples below show what works and what doesn't, so you can check your photo before submitting it. Following these guidelines ensures your Credential will be processed quickly and your photo will look professional on your ID. ## Requirements For your ID photo to be approved, it must meet the following requirements: ### Photo Composition - **Passport-style**: The photo must be passport-style and show your **full head and the top of your shoulders** - **Size**: Your face and shoulders should fill **most of the image (approximately 70–80%)** - **Position**: You must look **directly at the camera** with your head in a natural position - **No objects**: No hands, objects, or other foreign elements should appear in the photo ### Face Visibility - **Eyes**: Must be **open, clearly visible**, and not covered by hair - **Glasses**: **Clear lenses are allowed**, but tinted glasses or strong reflections are not permitted - **Hair**: Your face must be fully visible. Ensure that hair does not cover your eyes, cheeks, or forehead ### Background & Quality - **Background**: The photo must be taken against a **light, solid-colored** background - **Angle**: The photo must be taken **straight on**, facing forward - **Quality**: In **sharp focus**, clear, and with **good contrast** ### Head Coverings - **Religious head coverings only**: They must be worn so that your **chin, forehead, and both cheeks are clearly visible**. The head covering must not **cast shadows over your face** ## ✅ Acceptable Photos ![Examples of acceptable ID photos showing proper lighting, clear glasses, and correctly worn religious head covering](./_images/photo-examples-acceptable.png) **What's allowed:** - **Looking directly at camera** with head straight - **Passport-style photo** (full head and top of shoulders) - **Plain, light-colored background** - **Even lighting**, no shadows on face - **Clear glasses** (eyes visible through lenses) (8): Glasses are allowed as long as the lenses are clear and your eyes are clearly visible. No glare or tinted lenses. - **Religious head coverings** (chin, forehead, and cheeks must be visible) (9): Head coverings are allowed if they are of a religious nature, and your chin, forehead, and both cheeks are visible. No shadows over your face. - **Face fills 70–80%** of the photo ## ❌ Unacceptable Photos ![Examples of unacceptable photos showing shadows, busy backgrounds, hair covering face, sunglasses, hats, and incorrect head position](./_images/photo-examples-unacceptable.png) **What's not allowed:** - **Shadows on your face (1)**: Your entire face must be well-lit. Shadows over parts of your face make the photo unsuitable. - **Busy or patterned background (2)**: The background must be light, solid-colored, and neutral to provide good contrast against your face. - **Hair covering face (3)**: Your face must be fully visible. Ensure that hair does not cover your eyes, cheeks, or forehead. - **Eyes not visible (4)**: Your eyes must be open and clearly visible. No objects or hair should cover them. - **Non-religious head covering (5)**: Only religious head coverings are allowed, and then your chin, forehead, and both cheeks must be visible. The head covering must not cast shadows. - **Not looking directly at camera (6)**: You must look straight ahead, with your head in a natural position. The photo must be taken from the front. ## Quick Tips - Use natural or bright, even lighting - Stand against a plain white or light-colored wall - Ensure your entire face is visible and well-lit - Remove non-religious headwear before taking the photo - Make sure your eyes are clearly visible --- ## Retningslinjer for ID-foto {#retningslinjer-for-id-foto} ID-fotoet for din ID-bærer må oppfylle disse kravene for å bli godkjent og brukt på din ID. Foto som ikke oppfyller disse standardene kan bli avvist, noe som kan forsinke ID-bærer-opprettelsesprosessen. Høy kvalitet på bildene er viktig for klar identifikasjon og profesjonelt utseende. Fotoet må være skarpt, i skarpt fokus og ha god kontrast slik at ansiktet ditt er tydelig gjenkjennelig. Uskarpe, pixellete eller dårlig opplyste bilder vil ikke oppfylle standardene som kreves for offisielle legitimasjoner. Bruk et passfoto med god belysning og enkel bakgrunn. Eksemplene nedenfor viser hva som fungerer og hva som ikke gjør det, slik at du kan sjekke fotoet ditt før du sender det inn. Ved å følge disse retningslinjene sikrer du at ID-bærer blir behandlet raskt og at fotoet ditt ser profesjonelt ut på din ID. ## Krav For at ID-fotoet skal bli godkjent, må det oppfylle følgende krav: ### Foto-sammensetning - **Passfoto**: Bildet skal ha karakter av et passfoto og vise **hele hodet samt toppen av skuldrene** - **Størrelse**: Ansiktet med skuldre bør fylle **mesteparten av bildet (omtrent 70–80%)** - **Posisjon**: Du skal se **rett inn i kameraet** med hodet i naturlig posisjon - **Ingen objekter**: Ingen fremmedlegemer som hender eller andre objekter skal vises i ID-foto ### Ansikts-synlighet - **Øyne**: Skal være **åpne, klart synlige** og ikke dekket av hår - **Briller**: **Klare glass er tillatt**, men ikke farget glass eller sterke refleksjoner - **Hår**: Ansiktet skal være fullt synlig. Sørg for at hår ikke skjuler øyne, kinn eller panne ### Bakgrunn og kvalitet - **Bakgrunn**: Fotoet må være tatt mot en **lys, ensfarget bakgrunn** - **Vinkel**: Fotoet må være tatt **rett forfra** - **Kvalitet**: I **skarp fokus**, klart og med **god kontrast** ### Hodeplagg - **Kun religiøse hodeplagg**: De må bæres slik at **hake, panne og begge kinn er godt synlige**. Hodeplagget må ikke **kaste skygger over ansiktet** ## ✅ Godkjente fotoer ![Eksempler på godkjente ID-foto med korrekt belysning, klare briller og korrekt brukt religiøst hodeplagg](./_images/photo-examples-acceptable.png) **Eksempler på godkjente ID-foto:** - **Rett blikk og god belysning (7)**: Personen ser rett inn i kamera, med jevn lyssetting uten skygger. Bakgrunnen er lys og ensfarget. - **Briller med klare glass (8)**: Briller er tillatt så lenge glassene er klare og øynene er tydelig synlige. Ingen refleks eller farget glass. - **Religiøst hodeplagg korrekt brukt (9)**: Hodeplagg er tillatt dersom det har religiøs karakter, og hake, panne og begge kinn er synlige. Ingen skygger over ansiktet. ## ❌ Ikke godkjente fotoer ![Eksempler på ikke godkjente fotoer som viser skygger, urolig bakgrunn, hår som dekker ansiktet, solbriller, hatter og feil hodeposisjon](./_images/photo-examples-unacceptable.png) **Vanlige feil ved ID-foto – unngå dette:** - **Skygger i ansiktet (1)**: Hele ansiktet må være godt belyst. Skygger over deler av ansiktet gjør bildet uegnet. - **Urolig eller mønstret bakgrunn (2)**: Bakgrunnen skal være lys, ensfarget og nøytral for å gi god kontrast mot ansiktet. - **Hår som dekker ansiktet (3)**: Ansiktet skal være fullt synlig. Sørg for at hår ikke skjuler øyne, kinn eller panne. - **Øyne ikke synlige (4)**: Øynene må være åpne og tydelig synlige. Ingen gjenstander eller hår skal dekke dem. - **Hodeplagg som ikke er religiøst (5)**: Kun religiøse hodeplagg er tillatt, og da må hake, panne og begge kinn være synlige. Hodeplagget må ikke lage skygger. - **Ser ikke rett i kamera (6)**: Personen skal se rett frem, med hodet i naturlig posisjon. Bildet må tas forfra. ## Tips - Bruk naturlig eller sterk, jevn belysning - Still deg mot en hvit eller lys vegg - Sørg for at hele ansiktet er synlig og godt opplyst - Ta av ikke-religiøst hodeplagg før du tar fotoet - Sørg for at øynene er tydelig synlige --- ## Credential Management Credential Management in Breeze helps you create, issue, and manage the IDs people use — physical cards and mobile IDs — from start to finish. This page gives you the essentials and points you to detailed guides. ## What is a Credential? - A Credential is an ID you give to a person, like a staff ID-card or a mobile ID on their phone. - It’s used to identify the person and, if you choose, to control access (doors, services, systems). ## The kinds of Credentials Breeze supports - Card: A physical card you can print, personalize, and (if needed) encode for access. - Mobile ID: A digital ID on a person’s phone that you can issue or revoke. ## How Credentials are created (in simple terms) 1. Pick a design: Choose the ready-made template you want to use. 2. Fill in details: Add the person’s info (name, photo, title, etc.). 3. (Optional) Invite the person: Send them a link to provide or confirm details (“Duo ID” invite). 4. Make it: Produce the card or issue the mobile ID. 5. Check it: Review the result (quality check) before it goes live. 6. Activate: Make it ready for day-to-day use. ## Common tasks you can do - Create one Credential or many at once (batch). - Update photos and details; preview how the card will look. - Activate or replace a Credential when needed. - Track progress (requested → in production → quality check → ready to use) at a glance. - See if Duo ID invites were delivered or opened; resend when needed. ## The Credential journey (lifecycle) at a glance - Draft: You start the Credential and fill in details. - Request/Review: Someone reviews and approves if your policy requires it. - In production: The card is being printed/encoded, or the mobile ID is being issued. - Quality check: Final checks by the production team to make sure everything looks right. - Ready to use: The Credential is active. - Replace: Make a new one to supersede the old one. - Activate: If connected to a system, activate the Credential to make it ready for day-to-day use. - Deactivate: If connected to a system, deactivate the Credential to make it no longer usable. ## Duo ID (optional invite) - Send the person a simple email link to provide a photo or missing details. - Breeze shows whether the email was delivered and opened, so you know if follow-up is needed. - Review the Credential before going to production. ## Batches (many at once) - Create a larger group of Credentials in one go (visitor cards, event cards, temporary cards, etc.). - Each Credential still gets its own unique number and status. ## Good practices - Keep only what you need: Create and activate Credentials for the right people at the right time. - Review regularly: Remove or deactivate Credentials that are no longer needed. - Use the invite when helpful: Let people supply their own photo/details to reduce admin work. - Act fast on lost Credentials: Deactivate or replace right away. ## FAQs - What’s the difference between a card and a mobile ID? - A card is physical; a mobile ID lives on the person’s phone. Both can be managed the same way: create, activate, deactivate, or replace. - Can I make many Credentials at once? - Yes. Use a batch to create a group quickly while keeping each Credential trackable. - What if a Credential is lost? - Deactivate it immediately, then issue a replacement. - How do I know if someone received their Duo ID invite? - Breeze shows if the Duo ID invite was delivered and whether it was opened. ## Key takeaways - Credentials are the IDs you issue (card or mobile). - Breeze makes it easy to create, check, activate, deactivate, replace, and track them. - Optional invites help people provide their own details, and you can see if invites were delivered or opened. ## Related documentation - **[ID Photo Requirements](./id-photo-requirements)** — Guidelines for photos used on credentials. - **[Email History](./email-history)** — Track email delivery status and timeline for credential-related emails. - **[External Data Lookup](./external-data-lookup)** — Use external data lookup to automatically retrieve person information during credential ordering. - **[Mobile Credential Templates](/docs/template-management/mobile-credential-templates/)** — Configure how mobile IDs are issued. - **[Customizable List Views](./customizable-list/)** — Configure credential list views. - **[Data Export](./data-export)** — Export credential data. - **[Using List View](./using-list-view)** — Work with credential lists. ## Next steps - **[Credential Statuses](./credential-statuses)** — Understand what each status means and how credentials move through their lifecycle. - **[Understanding Mobile Credential Lifecycle](./mobile-credentials-lifecycle)** — Learn about states and transitions. - **[Using List View](./using-list-view)** — Work with credential lists and manage credentials. --- ## Mobile Credential Lifecycle Mobile Credentials follow a structured lifecycle from creation to activation and eventual deactivation or deletion. Understanding this lifecycle helps you manage Credentials effectively and know what to expect at each stage. ## Lifecycle Overview Mobile Credentials move through three main states during their operational life: **Inactive**, **Active**, and **Deactivated**. Each state represents a specific phase in the Credential's lifecycle and determines what the Credential can do and what actions you can take. Think of it like this: - **Inactive**: The Credential is created but not yet provisioned to the mobile ID provider - **Active**: The Credential is live and working — the person can use their mobile ID to access doors and services - **Deactivated**: The Credential is temporarily turned off — useful when someone is on leave or has lost their phone temporarily ### Provision Methods How a Mobile Credential moves from creation to active depends on the **Provision Method** setting in the Mobile Credential Template: - **Automatic**: The Credential skips the Inactive state and goes directly to **Active**. It's automatically provisioned (sent to the mobile ID provider and the person's device) without manual intervention. - **Manual**: The Credential starts in the **Inactive** state. An administrator must manually activate it to move it to Active and provision it. **Note**: The Inactive state may be skipped entirely if your template uses Automatic provisioning. Check your Mobile Credential Template settings to see which method is configured. Knowing which state a Credential is in helps you understand whether it will work for access control and what you need to do next. ![Credentials list showing different statuses](./_images/credentials-list-english.png) The Credentials list shows the current status of each Credential, making it easy to see which ones are Active, Deactivated, or in other states. ## Lifecycle States ### 1. Inactive State **Description**: The Credential has been created but is not yet active for use. This is the initial state after a Mobile Credential is created when using **Manual** provisioning. At this stage, the Credential exists in Breeze but hasn't been synchronized with the mobile ID provider (like STid Mobile ID), so it won't work for access control yet. **When you'll see this**: - Only when using **Manual** provision method in your template - Right after creating a new Mobile Credential (if Manual provisioning is configured) - When a Credential is first created from a template with Manual provisioning - Before the Credential has been synchronized with the provider **Note**: If your template uses **Automatic** provisioning, the Credential skips this state and goes directly to Active. **What this means**: - The Credential exists in your system with all the person's information - It hasn't been sent to the mobile ID provider yet, so the person can't use it - The mobile ID (vCard) is not on the person's phone - An administrator needs to manually activate it before it becomes usable **Visual Indicator**: Yellow status indicator (shows it's pending) **What you can do**: Activate it to make it usable (moves to Active), or delete it if it was created by mistake **Next Possible States**: Active (when manually activated), Deleted (if removed) ### 2. Active State **Description**: The Credential is fully operational and can be used for access control. This is the "working" state. When a Mobile Credential is active, the person can use their mobile ID to access doors, services, and systems. The Credential has been synchronized with the mobile ID provider, and the mobile ID (vCard) is available on their phone. **What this means**: - The Credential is synchronized with the mobile ID provider (like STid Mobile ID) - The mobile ID (vCard) has been sent to and/or created on the person's device - The person can use their phone to access doors and services - The Credential is fully functional and working as expected **When you'll see this**: - **With Automatic provisioning**: Immediately after creating the Credential (it skips Inactive and goes straight to Active) - **With Manual provisioning**: After successfully activating an Inactive Credential - When a deactivated Credential is reactivated - During normal day-to-day operation **Visual Indicator**: Green status indicator (shows it's working) **What you can do**: This is the normal operational state. You can deactivate it if needed (e.g., lost phone, temporary leave), or delete it if it's no longer needed **Common use cases**: - Regular staff members with active access - Visitors who need temporary access - Contractors working on-site **Next Possible States**: Deactivated (if temporarily disabled), Deleted (if permanently removed) ![Active Credential details page showing green Active status and available actions](./_images/credential-active-english.png) An Active Credential shows a green status indicator and provides options to deactivate, delete, or re-order. ### 3. Deactivated State **Description**: The Credential is temporarily disabled but can be reactivated. This state is useful when you need to temporarily disable access without permanently removing the Credential. When deactivated, the mobile ID (vCard) is removed from both the provider and the person's device, so they can't use it for access control. **What this means**: - The Credential is temporarily turned off — it won't work for access control - The mobile ID (vCard) has been removed from the provider and the person's phone - The Credential remains in your system with all its information - You can reactivate it later when needed — no need to recreate it **When you'll see this**: - After you deactivate an active Credential - When someone loses their phone temporarily - During a leave of absence or temporary suspension - When investigating security concerns **Visual Indicator**: Yellow status indicator (shows it's temporarily disabled) **What you can do**: Reactivate it when ready, or delete it if it's no longer needed permanently **Common use cases**: - Lost or stolen phones (until recovered or replaced) - Temporary leave or suspension - Security investigations - Temporary access revocation **Important**: Deactivation is temporary. If you need to permanently remove a Credential, use Delete instead. **Next Possible States**: Active (if reactivated), Deleted (if permanently removed) ![Deactivated Credential details page showing yellow Deactivated status](./_images/credential-deactivated-english.png) A Deactivated Credential shows a yellow status indicator. Notice the "Activate Credential" button is available to restore access. ## State Transitions Understanding how Credentials move between states helps you know what to expect and troubleshoot issues. ### Creation → Active (Automatic Provisioning) **When this happens**: A Credential is created using a template with **Automatic** provision method **What triggers it**: Creating a new Mobile Credential automatically triggers provisioning **What happens during automatic provisioning**: 1. The Credential is created in Breeze 2. Breeze immediately connects to your mobile ID provider (currently STid Mobile ID) 3. The Credential is synchronized — all the person's information is sent to the provider 4. The provider sends an email to the person with a link to activate their mobile ID 5. The status is set to Active in Breeze (skipping Inactive) **Important — How STid Mobile ID works**: - The person receives an email with a link - **They must click the link on the device they'll be using** (the same device where they'll install the Mobile ID) - **The Mobile ID app must already be installed** on that device before they click the link - Once they click the link on the correct device, the vCard is installed and they can use their mobile ID **Note**: With Automatic provisioning, you won't see the Inactive state. The Credential goes directly to Active. However, the person must complete the email link process before they can actually use it. **Note for future providers**: Other mobile ID providers may work differently. Currently, Breeze supports STid Mobile ID. ### Creation → Inactive (Manual Provisioning) **When this happens**: A Credential is created using a template with **Manual** provision method **What triggers it**: Creating a new Mobile Credential with a template configured for Manual provisioning **What happens during creation**: 1. The Credential is created in Breeze with all the person's information 2. The Credential is set to **Inactive** state 3. No synchronization with the mobile ID provider happens yet 4. The mobile ID (vCard) is not sent to the person's device 5. The Credential remains in Inactive until manually activated **Why this happens**: With Manual provisioning, you control when the Credential becomes active. This allows you to: - Review Credentials before they go live - Batch activate multiple Credentials at once - Control the timing of access provision **What this means**: - The Credential exists in your system but won't work for access control yet - The person cannot use their mobile ID until you activate it - An administrator must manually activate it to move it to Active **Next step**: Activate the Credential to move it from Inactive to Active (see next section) ### Inactive → Active (Manual Provisioning) **When this happens**: You manually activate a Credential that's in the Inactive state **What triggers it**: An administrator activates the Credential from the Credential page **What happens during manual activation**: 1. Breeze connects to your mobile ID provider (currently STid Mobile ID) 2. The Credential is synchronized — all the person's information is sent to the provider 3. The provider sends an email to the person with a link to activate their mobile ID 4. The status is updated to Active in Breeze **Important — How STid Mobile ID works**: - The person receives an email with a link - **They must click the link on the device they'll be using** (the same device where they'll install the Mobile ID) - **The Mobile ID app must already be installed** on that device before they click the link - Once they click the link on the correct device, the vCard is installed and they can use their mobile ID **What you need**: - Valid mobile ID provider connection (check your template configuration) - Successful synchronization (no network or provider errors) - No configuration errors in the Credential template - Template must be configured with **Manual** provision method **How long it takes**: The activation in Breeze happens immediately (usually just a few seconds). However, the person must complete the email link process before they can actually use their mobile ID. **What to check if it fails**: - Mobile ID provider connection status - Template configuration (especially provider settings) - Network connectivity - Credential information is complete (especially email address) **After activation**: The Credential shows as Active (green indicator) in Breeze. The person must check their email and click the link on their device to complete setup. **Note for future providers**: Other mobile ID providers may work differently. Currently, Breeze supports STid Mobile ID. ### Active → Deactivated **When this happens**: You need to temporarily disable access for someone **What triggers it**: An administrator deactivates the Credential from the Credential page **What happens during deactivation**: 1. Breeze connects to the mobile ID provider 2. The mobile ID (vCard) is removed from the provider 3. The mobile ID is removed from the person's device (if possible) 4. The status is updated to Deactivated in Breeze 5. The person can no longer use their mobile ID for access control **Why you might do this**: - Someone lost their phone and you want to prevent unauthorized access - Temporary leave or suspension - Security investigation - Testing or troubleshooting **What you need**: - Administrator permissions - The Credential must be in Active state (you can't deactivate an Inactive Credential — just activate it instead) When deactivating a Credential, you'll need to confirm by checking the checkbox before the Deactivate button becomes enabled. **Important notes**: - This is temporary — you can reactivate it later without recreating it - The Credential information stays in your system - If you need to permanently remove it, use Delete instead **After deactivation**: The Credential shows as Deactivated (yellow indicator), and access is immediately revoked. ### Deactivated → Active **When this happens**: You want to restore access for someone who had their Credential deactivated **What triggers it**: An administrator reactivates the Credential from the Credential page **What happens during reactivation**: 1. Breeze connects to the mobile ID provider (currently STid Mobile ID) 2. The Credential is re-synchronized with the provider 3. The provider sends an email to the person with a link to reactivate their mobile ID 4. The status is updated to Active in Breeze **Important — How STid Mobile ID works**: - The person receives a new email with a link - **They must click the link on the device they'll be using** - **The Mobile ID app must already be installed** on that device - Once they click the link, the vCard is installed again and they can use their mobile ID **Why you might do this**: - Someone recovered their lost phone - A temporary leave or suspension has ended - A security investigation is complete - You want to restore normal access **What you need**: - Administrator permissions - The Credential must be in Deactivated state - Valid Credential configuration (same requirements as initial activation) **Benefits of reactivation**: - No need to create a new Credential — all the original information is preserved - Quick and simple process - Maintains Credential history **After reactivation**: The Credential shows as Active (green indicator), and the person can use it immediately. ### Any State → Deleted **When this happens**: You need to permanently remove a Credential from the system **What triggers it**: An administrator deletes the Credential from the Credential page **What happens during deletion**: 1. Breeze connects to the mobile ID provider 2. The mobile ID (vCard) is removed from the provider 3. The mobile ID is removed from the person's device (if possible) 4. Personal details are anonymized in Breeze 5. The status is updated to Deleted 6. The Credential is permanently removed (cannot be recovered) **Why you might do this**: - Someone has left the organization permanently - The Credential was created by mistake - Compliance or data retention requirements - Cleanup of old or unused Credentials **Important warnings**: - ⚠️ **This is permanent** — you cannot undo deletion - ⚠️ **The Credential cannot be reactivated** — you'll need to create a new one if needed later - ⚠️ **Personal details are anonymized** — but the Credential record may remain for audit purposes **When to use Delete vs. Deactivate**: - **Use Deactivate** when you might need the Credential again (temporary leave, lost phone, etc.) - **Use Delete** when you're certain the Credential is no longer needed (person left, mistake, etc.) **What you need**: - Administrator permissions - Confirmation that you want to permanently remove it (you'll be asked to confirm) **After deletion**: The Credential is removed from active lists, though it may appear in audit logs with anonymized data. ## Common Scenarios ### New Employee Onboarding **With Automatic Provisioning**: 1. Create the Mobile Credential → goes directly to **Active** state 2. STid sends an email to the employee with a link 3. Employee clicks the link on their device (where Mobile ID app is installed) 4. Employee can now use their mobile ID **With Manual Provisioning**: 1. Create the Mobile Credential → **Inactive** state 2. Activate it → **Active** state 3. STid sends an email to the employee with a link 4. Employee clicks the link on their device (where Mobile ID app is installed) 5. Employee can now use their mobile ID **Important**: Make sure the employee has the Mobile ID app installed on their device before they click the email link. They must click the link on the device they'll be using for access. ### Employee on Temporary Leave 1. Credential is **Active** 2. Deactivate it → **Deactivated** state (removes access) 3. When they return, reactivate → **Active** state again - STid sends a new email with a link - Employee clicks the link on their device - Access is restored ### Lost or Stolen Phone 1. Credential is **Active** 2. Immediately deactivate → **Deactivated** state (removes access immediately) 3. If phone is recovered, reactivate → **Active** state - STid sends a new email with a link - Person clicks the link on their recovered device - Mobile ID is restored 4. If phone is not recovered, issue a new Credential and delete the old one - New Credential will send a new email link - Person uses their new device to click the link ### Employee Leaves Organization 1. Credential is **Active** 2. Delete it → **Deleted** state (permanent removal) ### Credential Created by Mistake 1. Credential is in **Inactive** (Manual) or **Active** (Automatic) state 2. Delete it → **Deleted** state ## Troubleshooting ### Credential Won't Activate (Manual Provisioning) If a Credential stays in the **Inactive** state after you try to activate it: - Check your mobile ID provider connection in the template settings - Verify network connectivity - Check for error messages in the Credential details - Ensure all required Credential information is complete - Review template configuration for any issues ### Credential Shows as Active But Doesn't Work If a Credential is **Active** but the person can't use it: - Verify the mobile ID (vCard) is actually on their device - Check if there are sync issues with the provider - Confirm the Credential is properly configured in the access control system - Try deactivating and reactivating to re-sync ### Credential was activated, but no vCard was sent to the person's device **This is normal and expected.** With STid Mobile ID (the current provider), the person receives an email with a link and must complete a process before the vCard appears on their device. **How STid Mobile ID works**: 1. When you activate a Credential, STid sends an email to the person's email address 2. **The person must click the email link on the device they'll be using** (this is important — they must use the correct device) 3. **The Mobile ID app must already be installed** on that device before clicking the link 4. Once they click the link, the vCard is installed and they can use their mobile ID **Normal delays**: - **Email delivery**: Usually just a few minutes, but can vary depending on email delivery times - **For new Credentials**: After clicking the link, the vCard typically installs within a few minutes - **Replacing existing vCards**: If the person already has a vCard from STid: - The old vCard must be removed first, which can take up to **15 minutes** - Only after the old vCard is removed will the new email be sent - Then they must click the new link on their device - This is a safety feature to prevent conflicts between old and new Credentials **What to expect**: - **For new Credentials**: - Wait a few minutes for the email to arrive - The person must check their email and click the link on their device - Make sure they click it on the device where they have the Mobile ID app installed - **For replacements with STid**: - Wait up to 15 minutes for the old vCard to be removed - Then the person will receive a new email with a link - They must click the new link on their device - The Credential status will show as **Active** in Breeze even while waiting for the person to complete the email link process **Common issues**: - **Person didn't receive email**: Check their spam folder, verify the email address in the Credential is correct - **Person clicked link on wrong device**: They must click the link on the device where the Mobile ID app is installed - **Mobile ID app not installed**: The app must be installed before clicking the email link - **Person clicked link before app was installed**: They may need to contact support or request a new email link **When to be concerned**: - If the person hasn't received the email after 10-15 minutes - If more than 15-20 minutes have passed (for STid replacements) and no email has arrived - If the Credential status shows an error in Breeze - If there are error messages in the Credential details **What to check**: - Verify the person's email address is correct in the Credential - Confirm the person checked their spam/junk folder - Ensure the person clicks the link on the correct device (where Mobile ID app is installed) - Verify the Mobile ID app is installed on their device - Check the Credential status in Breeze for any error indicators - Review the Credential details for any sync errors ## Quick Reference | State | What It Means | Can Person Use It? | Can You Reactivate? | | --------------- | --------------------------------------- | ------------------ | --------------------------- | | **Inactive** | Created but not activated (Manual only) | ❌ No | N/A — activate it first | | **Active** | Working and usable | ✅ Yes | N/A — already active | | **Deactivated** | Temporarily disabled | ❌ No | ✅ Yes — can reactivate | | **Deleted** | Permanently removed | ❌ No | ❌ No — must create new one | **Note**: Inactive state only appears with Manual provisioning. With Automatic provisioning, Credentials go directly to Active. ## Related Documentation - **[Credential Management Overview](/docs/credential-management/)** — Learn about Credentials and what you can do with them - **[Credential Statuses](/docs/credential-management/credential-statuses)** — Detailed explanation of all Credential statuses (including cards) - **[Mobile Credential Templates](/docs/template-management/mobile-credential-templates/)** — Configure how mobile IDs are issued --- ## Using the Credentials List View Imagine you're managing 300 Credentials and need to quickly find those that expired last week, or you've just onboarded 50 new employees and want to export their Credential data for your records. The Credentials list view is your command center for all of this—and more. This guide shows you how to make the list view work for you, with practical examples and tips you can use right away. :::note[Required Roles] **Required role**: `Admin` To use the features in this guide, you need to have the Admin role. **Domain View**: If you're working in a domain's main Tenant, you can also use Domain View to see Credentials across all sub-Tenants in your domain. Domain View requires Admin access on the main Tenant. ::: ## Why the List View Matters The list view isn't just a table of Credentials—it's your main tool for: - **Finding what you need quickly**: Instead of scrolling through pages, use filters to jump straight to the Credentials you're looking for - **Getting the big picture**: See status, creation dates, and key info at a glance - **Working efficiently**: Bulk actions let you manage dozens of Credentials in seconds instead of clicking through them one by one **When to use this view**: Pretty much always! It's the default view when you open "Manage Credentials," and it's designed to be your starting point for most Credential management tasks. ## Getting Started: Understanding the Interface Each row in the list represents one Credential. Here's what you need to know: - **Double-click a row** or **click the arrow icon** to open the full Credential details - **Hold Ctrl and click** to open Credentials in a new tab (handy when you're comparing multiple Credentials) :::tip[Quick Navigation Tip] Use Ctrl+Click on the arrow icon when you want to keep your place in the list while checking Credential details. It's perfect when you're reviewing multiple Credentials in sequence. ::: ### Viewing Credentials: Tenant View vs Domain View If you're working in a domain's main Tenant, you'll see a view toggle in the top-right of the Manage Credentials page with two options: - **Tenant View**: Shows only Credentials from your current Tenant (default behavior) - **Domain View**: Shows Credentials from all sub-Tenants in your domain **When to use Domain View**: Use Domain View when you need to find a Credential but don't know which sub-Tenant owns it. For example, if someone asks you to find "John Smith's Credential" but you're not sure which department (Tenant) he belongs to, Domain View lets you search across the entire domain. **What you'll see in Domain View**: - A "Tenant - Name" column appears in the list, showing which Tenant each Credential belongs to - All existing filters and sorting work the same way - You can filter by Tenant name to narrow down results - Export is not available in Domain View (use Tenant View if you need to export) **Setting your default view**: If you're an Admin with User Administration permissions on the main Tenant, you can click "Save as Default" next to the view toggle to make Domain View (or Tenant View) your default. The list will automatically open in your preferred view the next time you access it. ![Domain View toggle](./_images/dii-001-domain-view-toggle.png) _Caption: The Tenant View / Domain View toggle appears in the top-right of the Manage Credentials page for main Tenants._ ![Domain View with tenant column](./_images/dii-001-domain-view-with-tenant-column.png) _Caption: When Domain View is active, the list shows Credentials from all sub-Tenants in the domain, with a "Tenant - Name" column indicating which Tenant each Credential belongs to._ ### Make It Fit: Customizing Your View Ever wish you could see more of that "Requester Email" column, or make the status badges wider? You're in luck. **Resize columns** by dragging the divider between column headers. Your preferences are saved automatically in your browser, so they'll stay exactly how you like them. Don't worry—these settings are specific to your browser, so other team members won't see your layout changes. ## Find Credentials Fast (Filtering) Here's where the list view really shines. Let's say you need to find all Credentials for people with "Smith" in their name. **Here's how you'd do it:** 1. Look for the filter icon in the "Person - Last name" column header 2. Click it and type "Smith" in the search box 3. The list updates instantly to show only Credentials matching your search But filters can do so much more than that. Let's look at what each field type can do: | Field Type | What You Can Do | Real Example | | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Text** | Contains | "Type 'John' to find all Johns, Johnathans, and Johnson Credentials" | | **Numbers** | Equals, Greater than, Less than | "Find Credential #13530 exactly, or all Credentials numbered above 10000" | | **Dates** | Before, After, Between, On | "Show me all Credentials created after January 1, 2024" or "Credentials created between March and April 2024" | | **Status** | Multi-select dropdown | "Show only Active and Deactivated Credentials" (perfect for excluding old test data) | ![Filtering Options](./_images/filtering-options.png) **Here's a powerful tip**: You can combine multiple filters to create very specific searches. For example: - Find Credentials created in the last 30 days **and** with status "Active" - Show Credentials for people with "Martinez" in their name **and** created before a specific date :::tip[Pro Tip] Start broad, then narrow down. If you're looking for something specific, add one filter at a time and watch the results shrink. This helps you understand which filters are actually helping you find what you need. ::: **Don't forget**: When you're done filtering, use the reset button in the top filter bar to clear all filters and see your full list again. ## Sort It Your Way Want to see the newest Credentials first? Or maybe you need to find Credentials in alphabetical order by name? **Here's how sorting works:** 1. Click any column header (like "Order date" or "Person - First name") 2. The list sorts immediately—look for the ↑ or ↓ arrow in the column header 3. Click again to reverse the order **Example**: Click "Order date" once to see newest first (↓), click again to see oldest first (↑). Perfect for finding that Credential you know was created last week but can't remember the exact details. :::note[Current Limitation] At the moment, you can only sort by one column at a time. Multiple column sorting isn't available yet, but it's on the roadmap! ::: ## Work Smarter with Bulk Actions Managing Credentials one at a time works fine for small tasks, but when you need to handle many at once, bulk actions save you time and clicks. ### How It Works 1. **Select Credentials** using the checkboxes in the first column 2. Watch the action buttons update—they'll show how many items you've selected (e.g., "Delete 5 Credentials") 3. Choose your action from the available buttons **Available bulk actions** (what you see depends on your role): | Action | Required Role | What It Does | | ------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------- | | **Delete Credentials** | Admin | Permanently remove selected Credentials from the system | | **Reproduce Credentials** | System Admin | Create new versions of selected Credentials (useful for reissuing) | | **Export Search Results** | Super Admin and Data Exporter | Download the selected Credentials as a file for reporting or backup (not available in Domain View) | :::warning[Before Bulk Deleting] Deleting Credentials is permanent! The system will ask you to confirm before anything is deleted, but make sure you've selected the right Credentials. When in doubt, export them first as a backup. ::: **For large selections** (more than 100 items), you'll see helpful options: - Select just the first 100 items (if that's all you need) - Select the first 300 items - Clear your selection and start over These options help you avoid accidentally selecting thousands of Credentials when you only need a subset. ## Common Scenarios Here are real-world situations where the list view features really come in handy: ### Scenario 1: Finding Expired Credentials **The situation**: Your security policy requires reviewing all Credentials that expired in the last month. **How to do it**: 1. Filter by "Card valid until date" and set the date you want to filter by 2. Sort by date to see the most recently expired first 3. Review or export as needed ### Scenario 2: Bulk Export After Onboarding **The situation**: You've just onboarded 50 new employees and need to export their Credential data for HR records. **How to do it**: 1. Filter by "Order date" to show Credentials created in the last week 2. Select all the new employee Credentials using the checkbox in the header (selects all on the current page) 3. Click "Export Search Results" 4. Download your file with all the Credential data ### Scenario 3: Cleanup After Employee Departure **The situation**: Ten employees left last month, and you need to deactivate or delete their Credentials. **How to do it**: 1. Filter by their names or email addresses 2. Select all their Credentials 3. Use bulk delete (if permanent removal) or manually deactivate them individually :::tip[Time Saver] If you're doing regular cleanup, create a filter for "Status: Deactivated" and sort by date. This helps you find old deactivated Credentials that might need permanent deletion. ::: ### Scenario 4: Finding a Specific Credential When You Only Know Partial Info **The situation**: Someone says "I think the employee number starts with 13..." or "It's for someone named Maria, but I'm not sure of the last name." **How to do it**: 1. Use the "Personnel number" filter and type "13" to see all Credentials where the personnel number starts with 13 2. Or filter "Person - First name" with "Maria" to narrow it down 3. Browse the filtered results—much faster than scrolling through everything! ### Scenario 5: Finding a Credential When You Don't Know Which Tenant Owns It **The situation**: You're working in a domain's main Tenant and need to find a Credential, but you don't know which sub-Tenant it belongs to. **How to do it**: 1. Switch to **Domain View** using the toggle in the top-right 2. Use filters (name, Credential number, status, or Tenant name) to narrow down results 3. The "Tenant - Name" column shows which Tenant each Credential belongs to 4. Open the relevant Credential from the list (double-click or use the row action) **Expected result**: You can search across all sub-Tenants in your domain without needing to know the specific Tenant ownership. ## Tips for Smooth Navigation Here are some quick tips to make your life easier: ### Keyboard Shortcuts - **Ctrl+Click** on any Credential to open it in a new tab (keep your place in the list!) - **Esc** to close side panels and dialogs - **Tab** to move between interactive elements ### Working with Large Lists - **Use filters, don't scroll**: If you have 500+ Credentials, scrolling through pages takes forever. A quick filter gets you there in seconds. - **Adjust page size**: Change how many rows show per page (10, 25, 50, 100) based on what you're doing. Viewing details? Smaller page size. Bulk selecting? Larger page size. - **Clear filters between searches**: Don't forget to reset filters when starting a new task—nothing's more confusing than wondering why your list is empty when you know you have 300 Credentials! ### Performance Tips - **Be specific with filters**: "Created in the last week" is better than "All Credentials" - **Avoid selecting 1000+ items**: If you need to work with that many, break it into smaller batches or use more specific filters - **Close detailed views when done**: Side panels are great, but closing them when you're finished keeps the interface snappy ## Safety Features We've built in several safeguards to prevent accidents: ### Confirmation Dialogs - **Destructive actions require confirmation**: When you delete Credentials, you'll see a confirmation dialog before anything happens - **Clear warnings**: The system tells you exactly what will happen before you commit ### Smart Selection Limits - **Large selection warnings**: If you try to select 100+ items, you'll see options to limit your selection or work with batches - **Clear selection option**: Always available if you change your mind ### Role-Based Protection - **Some actions are role-restricted**: You can only do what your role allows. If you don't see an action button, it's likely a permissions issue—check with your administrator ## Troubleshooting Common Issues Sometimes things don't work as expected. Here's how to solve the most common problems: | What's Happening | Likely Cause | What to Try | | ---------------------------------------- | -------------------------- | ------------------------------------------------------------------------- | | List won't load or shows an error | Network connectivity issue | Check your internet connection and refresh the page | | Everything feels slow | Too many results showing | Add a filter to narrow down the results | | Columns look wrong or are missing | Custom view settings | Check with your administrator—someone might have customized the list view | | Action buttons are grayed out or missing | You don't have permission | Verify your role assignments with your administrator | ### Getting Help If you're stuck: 1. **Check your role permissions first**—many "missing features" are actually permission-based 2. **Contact your tenant administrator**—they can check your access levels 3. **Reach out to support** if needed, and include: - Screenshots of what you're seeing - What you were trying to do (step by step) - Your browser and version (Chrome, Firefox, etc.) ## Related Documentation Now that you're comfortable with the list view: - **[Customizing the List View](/docs/credential-management/customizable-list/)** — Configure which columns appear and how they're arranged - **[Data Export](/docs/credential-management/data-export)** — Learn more about exporting Credential data for reporting and backups --- ## External Data Sources External Data Sources allow you to automatically retrieve person data from external systems during Credential ordering. When a Mobile Credential Template is configured with an external data source, operators can enter a search identifier (such as a personal identity number) to automatically populate Credential fields with data from the external system. ## Overview External Data Sources integrate Breeze with external person lookup services, such as: - **Norwegian Folkeregisteret (FREG)** — Norwegian National Registry for person data lookup - **SPAR** — Swedish population register (if configured) - **Breeze ID Connector** — A generic connector for your own OAuth-protected person lookup API When operators order Credentials using a template configured with an external data source, they can enter a search identifier to automatically retrieve and populate person information, reducing manual data entry and improving accuracy. ## What external data sources do External Data Sources: - **Automate data entry** — Retrieve person data automatically during Credential ordering - **Improve accuracy** — Reduce manual input errors by pulling data directly from authoritative sources - **Streamline workflows** — Speed up Credential ordering by pre-filling fields - **Support multiple sources** — Configure different data sources for different templates or use cases ## Who can configure external data sources :::note[Required Roles] **Required roles**: `System Administrator`, `Domain Administrator` To create or configure external data sources, you need one of the roles listed above. ::: ## How it works 1. **Administrator configures data source** — Create and configure an external data source in Domain Administration with the required credentials and settings 2. **Template connection** — Link the external data source to a Mobile Credential Template and configure field mappings 3. **Operator uses lookup** — When ordering a Credential, operators enter a search identifier (e.g., 11-digit Norwegian personal identity number) 4. **Automatic population** — System retrieves person data from the external source and populates Credential fields automatically 5. **Review and complete** — Operator reviews the populated data and completes any remaining Credential information ## Where to find it Navigate to **Domain Administration** → Select your domain → **External data sources** section. ## Configuring External Data Sources ### Creating a Norwegian Folkeregisteret (FREG) Data Source 1. Navigate to **Domain Administration** → Select your domain 2. Scroll to the **External data sources** section 3. Click **"Add"** to create a new external data source 4. In the dialog, configure: - **Scope**: Automatically set to your domain (read-only) - **Scope type**: Automatically set to DOMAIN (read-only) - **Data source type**: Select **"Norwegian Folkeregister"** (freg) - **Name**: Enter a descriptive name (e.g., "BLK FREG Oppslag") - **Client ID**: Enter your client ID (obtained from Sotera) - **Client secret**: Click **"Change client secret"** and enter your client secret 5. Click **"Test connection"** to verify your credentials are valid 6. Click **"Save"** to create the external data source :::info[Sotera Credentials] You need valid Sotera credentials to use Norwegian Folkeregisteret as an external data source. Contact Sotera to obtain your client ID and client secret. ::: ### Creating a Breeze ID Connector Data Source Use **Breeze ID Connector** when you want Breeze to retrieve person data from your own external API protected by OAuth 2.0 client credentials. #### What is Breeze ID Connector? Breeze ID Connector is a **generic** external data source type. It doesn’t connect to a specific national registry like FREG—instead, it lets Breeze call **your organization’s** person lookup API. You typically use it when you already have an internal or partner-provided service that can look up a person (for example, from HR, student records, or a national registry gateway), and you want Breeze to reuse that service during Credential ordering. #### How it works (high level) When an operator performs a lookup during Credential ordering: 1. Breeze requests an access token from your **OAuth token endpoint** (using the Client ID + Client secret you configure here). 2. Breeze calls your **Client URL** (your lookup API) and sends the operator’s search input. 3. Your API returns person data. 4. Breeze maps the returned data into Credential fields based on the template’s field mappings. #### What your organization must provide To use Breeze ID Connector, your organization (or integration partner) must provide: - **A person lookup API endpoint** (HTTPS recommended) that Breeze can reach. - **An OAuth 2.0 token endpoint** that supports the client credentials flow. - **A client registration** (Client ID + Client secret) that Breeze can use. - **A response contract** (JSON) that Breeze can understand. :::note[Network access] If your API is not publicly reachable, you must provide a network path that allows Breeze to call it (for example, VPN, allowlisting, or a hosted endpoint). ::: #### Response format requirements (important) Breeze ID Connector does **not** automatically adapt to any API response format. Your lookup service must return data in Breeze’s **person lookup format**. At minimum, the response must include an `identifier` field. Additional fields (such as name, address, department, email, etc.) can be included depending on what you want to map into your Credential Templates. **Reach out to Breeze support**—we can provide the expected response format and guidance for mapping. :::info[Managed connector option] If you prefer not to build and operate your own connector, Sotera can provide the Breeze ID Connector **as a managed service**—as long as you can make the required person data available to Breeze in an agreed and secure way. ::: 1. Navigate to **Domain Administration** → Select your domain 2. Scroll to the **External data sources** section 3. Click **"Add"** to create a new external data source 4. In the dialog, configure: - **Scope**: Automatically set to your domain (read-only) - **Scope type**: Automatically set to DOMAIN (read-only) - **Data source type**: Select **"Breeze ID Connector"** - **Name**: Enter a descriptive name (e.g., "HR Person Lookup") - **Client ID**: The OAuth client ID provided by your identity provider - **Client secret**: The OAuth client secret for the client ID - **Client URL**: The API endpoint Breeze will call to look up person data - **OAuth token endpoint**: The endpoint Breeze uses to request an access token 5. Click **"Test connection"** to verify the credentials work 6. Click **"Save"** to create the external data source ### Editing an External Data Source 1. Navigate to **Domain Administration** → Select your domain 2. Scroll to the **External data sources** section 3. Click **"Edit"** next to the external data source you want to modify 4. Update the configuration as needed 5. Click **"Save"** to apply changes ## Connecting External Data Sources to Templates After creating an external data source, you need to connect it to a Mobile Credential Template: 1. Navigate to **Templates** → **Mobile Credential** 2. Select or create a template 3. In the template editor, configure the external data source connection 4. Configure field mappings to map external data source response fields to Credential fields 5. Save the template For detailed instructions, see [Editing Templates](/docs/template-management/mobile-credential-templates/editing-templates). ## Limitations and Considerations - **Authentication requirements**: Some external data sources (like FREG) require Level 4 authentication (BankID) for natural person lookups - **Format requirements**: Each data source has specific format requirements for search identifiers (e.g., FREG requires exactly 11 digits) - **Rate limiting**: External data sources may have rate limits that apply to lookups - **Configuration scope**: External data sources are configured at the Domain level and can be used by templates within that domain ## Learn more - **[Mobile Credential Templates](/docs/template-management/mobile-credential-templates/)** — Create and manage templates for mobile ID Credentials - **[Editing Templates](/docs/template-management/mobile-credential-templates/editing-templates)** — Edit templates and configure external data source connections - **[Credential Management](/docs/credential-management/)** — Overview of credential management features --- ## Domain Administration > **TL;DR**: A Domain is a management container that groups multiple Tenants (organizations) together, allowing shared settings and centralized administration. Think of it as an umbrella structure where large organizations can manage multiple business units. Only System Administrators with the Domain Administrator role can manage domains. ## What is a Domain? A Domain in the Breeze solution is a high-level organizational structure that acts as a container for managing multiple Tenants (organizations or business units) and their settings. Think of it as a "system domain" - not to be confused with a website domain name (URL). ### Key Concepts - A Domain serves as an administrative umbrella that groups related Tenants together - Every Tenant in Breeze must belong to a Domain - Domains are particularly valuable for: - Large corporations managing multiple business units - Print service providers handling multiple customer organizations - Organizations requiring segregated management of different departments or divisions ### Common Use Cases 1. **Corporate Environment**: A large corporation might set up a Domain to manage multiple subsidiary companies or departments, each as separate Tenants 2. **Print Service Provider**: A print center might use a Domain to organize different customer organizations they serve 3. **Multi-Site Operations**: Organizations with multiple locations or production sites can use Domains to maintain consistent settings and configurations across their operation ### Domain Features - Centralized administration of multiple Tenants - Shared configuration settings across related Tenants - Customizable branding and communication settings - Standardized product offerings and service configurations - Enabling / Disabling features per domain - External Data Sources configuration for automatic person data lookup ### Domain Administration Access Domain management requires specific administrative privileges: - Users must have the **System Administrator** role - Additionally, they need the **Domain Administrator** task role - These combined roles ensure secure and controlled management of domain-wide settings and configurations Only users with both these roles can perform domain-level operations such as: - Creating and configuring new domains - Managing domain-wide settings - Configuring domain-specific features and integrations --- ## Product Deactivation The Product Deactivation feature provides a safe and controlled way to remove products from the Breeze system. This process ensures that all references to the product are properly handled and maintains a complete audit trail of the changes. ## Prerequisites :::note[Required roles] To deactivate products, you must have one of the following roles: - `System Administrator` - `Product Maintainer` ::: ## Overview When a product is deactivated, the system performs a comprehensive cleanup to ensure no orphaned references remain. The process includes: - Removing the product from domain and tenant settings - Handling associated card templates - Creating detailed audit logs ## Deactivation Process ### Step 1: Access the Product Drawer 1. Navigate to the Products section 2. Locate the product you want to deactivate 3. Click on the product to open the Product Drawer ### Step 2: Initiate Deactivation 1. In the Product Drawer, locate the "Deactivate" button 2. Click the button to start the deactivation process ### Step 3: Review Impact Before proceeding with the deactivation, the system will display a dialog showing: - Affected tenants that will have the product removed - Card templates that will be modified - Other system components that will be updated :::warning Review this information carefully. The deactivation process cannot be undone without manual intervention. ::: ### Step 4: Confirm Deactivation After reviewing the impact, click "Confirm" to proceed with the deactivation. ## System Changes When a product is deactivated, the following changes occur automatically: ### Domain Level Changes The product is removed from: - Domain whitelists - Default product lists - Transportation method configurations ### Tenant Level Changes For each affected tenant, the system: - Removes the product from tenant-specific whitelists - Removes the product from tenant default settings - Removes the product from tenant transportation methods - Resets production flow settings if the product was used in merge settings ### Card Template Changes For associated card templates, the system: - Removes the card type - Deactivates the card template - Creates audit logs for the changes ### System Status The product is: - Marked as inactive - Marked as deleted in the system - No longer available for new assignments or configurations ## Audit Trail The deactivation process creates detailed event logs for all changes, including: - Initial deactivation request - All affected object modifications - Final deactivation status ## Troubleshooting ### Common Issues #### Product Cannot Be Deactivated If you receive an error when trying to deactivate a product, check: - Your user role has sufficient permissions - You're currently browsing the correct system domain ## Best Practices 1. **Plan Ahead** - Schedule deactivations during low-usage periods - Inform affected users beforehand - Have a rollback plan ready 2. **Review Impact** - Carefully review all affected objects - Consider downstream effects on workflows - Check for custom integrations that might be affected 3. **Post-Deactivation** - Verify all changes were applied correctly - Check affected tenants and templates - Review audit logs for completeness --- ## Content Management and Formatting This guide explains how to create, edit, and manage Terms and Conditions content using the built-in Markdown editor. ## Creating and Updating Content ### Opening the Editor 1. Navigate to **Domain Administration** → **Select your domain** → **Terms and Conditions** 2. Click **MANAGE TERMS & CONDITIONS** 3. Click **UPDATE TERMS** to open the editor ![Terms and Conditions Editor](./_images/tac_editor.jpg) ### Creating a New Version 1. Enter a new version number - System suggests the next version (e.g., "1.0.9") - Must follow format X.Y.Z (e.g., 1.0.0) - Must be higher than current version 2. Edit your content - Use Markdown formatting (see [Markdown Support](#markdown-support)) - Use headings with # symbols - Structure content with clear sections - Click "PREVIEW" to check formatting 3. Preview your changes: ![Terms Preview](./_images/tac_preview.jpg) 4. Click "SAVE" to publish or "CANCEL" to discard changes ## Version Management ### Version History Access version history by clicking "VERSION HISTORY": ![Version History](./_images/tac_version_history.jpg) The history shows: - Version numbers - Creation dates - Authors - Actions (restore/edit) For each version you can: - View the content - See who created it - Check when it was created - Restore previous versions if needed ### Version Guidelines Choose the right version number based on your changes: #### Patch Version (1.0.8 → 1.0.9) - Fixing typos - Clarifying existing text - No policy changes #### Minor Version (1.0.9 → 1.1.0) - Adding new sections - Updating existing policies - Restructuring content #### Major Version (1.1.0 → 2.0.0) - Significant policy changes - Major restructuring - Changes affecting user rights ## Content Recommendations While the specific content of your Terms and Conditions is determined by your organization and legal team, here are some common elements often included in T&C documents: 1. **Structure Suggestions** - Clear section headings for easy navigation - Logical content organization - Consistent hierarchy - Professional formatting 2. **Common Sections** - Legal disclaimers - User obligations - Privacy policies - Contact information - Last updated date 3. **Formatting Best Practices** - Professional presentation - Readable layout - Proper spacing - Consistent style Note: The actual content and structure of your Terms and Conditions should be determined by your organization's needs and legal requirements. Breeze provides the tools to implement and manage your T&C system, but the specific content should be reviewed and approved by your legal team. ## Markdown Support The editor supports standard Markdown features: ### Text Formatting - Headers using `#` symbols (H1-H6) - **Bold text** using `**text**` - _Italic text_ using `*text*` - ~~Strikethrough~~ using `~~text~~` ### Lists and Structure - Bulleted lists (using `-` or `*`) - Numbered lists (using `1.`, `2.`, etc.) - Nested lists with indentation - Task lists with `- [ ]` and `- [x]` ### Advanced Elements - Tables with column alignment - Code blocks with syntax highlighting - Blockquotes for important notes - Horizontal rules for section breaks - Links to external resources - Images with alt text ## Helpful Online Markdown Tools To make content creation easier, you can draft and preview your content using these online Markdown editors before copying it to Breeze: ### Recommended Tools 1. **StackEdit** ([stackedit.io](https://stackedit.io)) - Real-time preview - Clean, professional interface - Export to multiple formats - Works offline - Free to use 2. **Dillinger** ([dillinger.io](https://dillinger.io)) - No account required - Side-by-side preview - Clean interface - Export options - Completely free ### VS Code Extensions If you use Visual Studio Code, these extensions can help: - "Markdown All in One" - formatting shortcuts and preview - "Markdown Preview Enhanced" - advanced preview features - "Markdown Table Formatter" - automatic table formatting ## Best Practices ### Content Organization 1. **Structure** - Use clear section numbering (1.1, 1.1.1) - Keep formatting consistent - Include all required legal sections - Maintain logical flow 2. **Version Control** - Make one change at a time - Write clear change descriptions - Review changes carefully - Keep version history organized 3. **User Communication** - Inform users of updates - Highlight important changes - Allow time for review - Monitor acceptance ### Writing Guidelines - Use clear, simple language - Break long paragraphs into bullet points - Include examples where helpful - Define technical terms - Be specific about user obligations ### Before Publishing - Preview all changes - Check formatting consistency - Verify links work - Review version number - Consider impact on users ## Common Issues and Solutions ### Version Number Errors - Check format is X.Y.Z - Ensure new version is higher - Version must be unique ### Content Not Saving - Verify version number - Check content isn't empty - Confirm admin permissions ### Preview Issues - Check Markdown syntax - Refresh the preview - Clear browser cache ## Need Help? - Review the [Setup Guide](./setup-guide.md) for initial configuration - See [User Acceptance Flow](./user-acceptance-flow.md) for understanding user experience - Contact support for technical assistance --- ## Terms and Conditions Management Managing Terms and Conditions (T&C) for your domain is essential for legal compliance and user transparency. This overview will help you understand the key features and capabilities. ## Quick Start Guide 1. Go to **Domain Administration** → **Select your domain** → **Terms and Conditions** 2. Click **MANAGE TERMS & CONDITIONS** 3. Enable Terms and Conditions using the toggle switch 4. Click **UPDATE TERMS** to create your first version ![Terms and Conditions Management](./_images/tac.jpg) ## Key Features - **Content Management**: Create and edit terms using a Markdown editor with live preview - **Version Control**: Track changes and manage multiple versions of your terms - **User Acceptance Flow**: Automated system for user acceptance of new terms - **Admin Dashboard**: Comprehensive management interface for terms and conditions ## Documentation Guides - [Setup Guide](./setup-guide.md) - Step-by-step instructions for initial configuration - [Content Management](./content-management.md) - Guidelines for creating and formatting content - [User Acceptance Flow](./user-acceptance-flow.md) - Understanding how users interact with terms ## Frequently Asked Questions ### Who needs to accept the terms? All users must accept your terms before accessing your services. This includes: - New users during their first login - Existing users when terms are updated ### What happens when terms are updated? When you publish a new version: 1. Users will be notified on their next login 2. They must accept the new terms to continue For detailed information about managing versions and user notifications, see the [Content Management Guide](./content-management.md#version-management). ### Need Help? Contact support for additional assistance or refer to our detailed guides linked above. --- ## Setting Up Terms and Conditions This guide explains how to set up Terms and Conditions for your domain. For content creation and management, see our [Content Management Guide](./content-management.md). ## Before You Start Make sure you have: - Domain administrator access - Your terms and conditions content ready (see [content recommendations](./content-management.md#content-recommendations)) - A clear understanding of your legal requirements ## Accessing the Dashboard 1. Open the Breeze Platform 2. Click on **Domain Administration** in the left sidebar 3. Select your domain from the domain list 4. Click on **MANAGE TERMS & CONDITIONS** in the **Terms and Conditions** section You should now see the Terms and Conditions dashboard: ## Dashboard Overview The dashboard provides: - Enable/disable toggle switch - Current version display - Last updated date - Version count - Content preview - "VERSION HISTORY" and "UPDATE TERMS" buttons ## Initial Setup Steps 1. Navigate to the Domain Management page 2. Find the "Terms and Conditions" section 3. Click on **MANAGE TERMS & CONDITIONS** 4. Toggle the switch to enable Terms and Conditions 5. You'll be prompted to create your initial version For detailed information about creating and managing content, see: - [Content Creation and Formatting](./content-management.md#creating-and-updating-content) - [Version Management](./content-management.md#version-management) - [Best Practices](./content-management.md#best-practices) ## Troubleshooting Initial Setup For content-related issues or version management, refer to the [Content Management Guide](./content-management.md#common-issues-and-solutions). ## Need Help? - Review the [Content Management Guide](./content-management.md) for detailed content creation instructions - See [User Acceptance Flow](./user-acceptance-flow.md) for understanding user experience - Contact technical support for setup assistance --- ## User Acceptance Flow When you enable Terms and Conditions for your domain, users will need to accept them before accessing your services. This guide explains how the acceptance process works and how to manage it effectively. ## How Users Experience Terms and Conditions ### First-Time Users When a new user tries to access your service for the first time, here's what happens: 1. The system automatically checks if they've accepted your terms 2. Since they haven't, they'll be redirected to the Terms and Conditions page 3. The page presents: - The current version of your terms - The date they were last updated - Accept and Decline buttons Once the user accepts the terms, they'll be: 1. Automatically redirected to their original destination 2. Able to use your services normally 3. Recorded in the system as having accepted that version ### Existing Users and Updates When you update your Terms and Conditions, here's what happens: 1. The next time a user tries to access any page in your service, they'll be automatically redirected to the Terms and Conditions page 2. They'll see: - The new version of the terms - Options to accept or decline This ensures users are aware of changes before they can continue using the service. ## Managing Multiple Domains If your organization has multiple domains, each can have its own Terms and Conditions. Here's how it works: Each domain maintains separate: - Terms and Conditions content - Version history - Acceptance records This means users might need to accept different terms for different domains. When accessing a new domain or when terms have been updated, they'll be redirected to accept the terms for that specific domain. ## The User Interface ### Terms and Conditions Page The Terms and Conditions page is designed to be clear and straightforward: - Clean, readable formatting - Clear version information - Easy-to-find accept/decline buttons ### Tracking Acceptance Status Users can check their acceptance status through their profile or settings: - Which version they've accepted - When they accepted it ## Common User Scenarios ### New Employee Onboarding When a new employee joins your organization: 1. They receive access to your services 2. On their first attempt to access any page, they're redirected to accept the terms 3. Once accepted, they get immediate access 4. Their acceptance is recorded for compliance ### Terms Update Process When you update your terms: 1. All users will be redirected to the Terms and Conditions page on their next access attempt 2. They must accept the new terms to continue 3. Access is restricted until they accept 4. They can review the changes before accepting ### Access Without Acceptance If a user hasn't accepted the current terms: 1. They'll be redirected to the Terms and Conditions page 2. A clear message will explain why they need to accept 3. Service access remains blocked until acceptance 4. All attempts are logged for security ## Best Practices for Users ### Reviewing Terms We recommend users: 1. Read through the entire document carefully 2. Pay special attention to any changes 3. Note the version number and acceptance date ### Handling Updates When redirected to review updated terms, users should: 1. Review the changes carefully 2. Understand how it affects their usage 3. Accept to maintain service access 4. Keep track of their acceptance history ## Support and Assistance If users encounter any issues: ### Common Questions "Why am I being redirected to the terms page?" - Terms have been updated - Your previous acceptance wasn't recorded - You're accessing a different domain "What happens if I decline?" - Access will be restricted - You can review and accept later - Your decline is recorded ### Getting Help Users can: 1. Contact their domain administrator 2. Check the help documentation [here](/troubleshooting/terms-and-conditions-access.md) Remember to provide: - The domain you're trying to access - The version you're trying to accept - Any error messages you see ## Next Steps - Learn how to [set up Terms and Conditions](./setup-guide.md) - Understand how to [create effective content](./content-management.md) - Review [administrator best practices](./content-management.md#best-practices) --- ## Available Data Fields The following data fields are available for use in the AMR integration: :::note[Important note] Even though a field is available, it may not always contain data. The data will be populated based on the Credential Template and the input form presented to the user. - Manual Input fields: These fields will remain empty unless the user has entered data. - Non-Manual Input fields: These fields will be automatically populated by the Breeze System. However, for Number Range fields, the values are determined by the Number Range settings in the Credential Template, if configured. ::: ### Data Fields | Source Object | Field Name | Description | Manual Input | Example | Data Type | | ------------- | ------------------------ | ----------------------------------------- | ------------ | ---------------------------- | -------------------- | | Credential | Id | The unique identifier of the Credential. | No | `66e1ad73bd756adad71c632c` | Text | | Credential | Status | Current status of the Credential. | No | `Active` | Text | | Credential | Card Number Manual | The manually entered card number. | Yes | `123456` | Text | | Credential | Card Valid Until Date | Expiration date of the Credential. | \* | `2022-12-31` | Date | | Credential | Company Name | Name of the company. | Yes | `Your Company Inc.` | Text | | Credential | Company Org No | Organization number of the company. | Yes | `123456789` | Text | | Credential | Extra 1-31 | Additional custom fields. | Yes | `Extra 1` | Text | | Credential | Extra Date 1-5 | Additional custom date fields. | Yes | `2022-12-31` | Date | | Credential | Message To Access Vendor | Message to the access vendor. | Yes | `Please allow access` | Text | | Credential | Order Cost Centre | Cost center of the order. | Yes | `123456` | Text | | Credential | Person First Name | First name of the person. | Yes | `John` | Text | | Credential | Person Last Name | Last name of the person. | Yes | `Doe` | Text | | Credential | Person Employee No | Employee number of the person. | Yes | `123456` | Text | | Credential | Person Country | Country of the person. | Yes | `Norway` | Text | | Credential | Person Country Code | Country code of the person. | Yes | `NO` | Text | | Credential | Person Department | Department of the person. | Yes | `IT` | Text | | Credential | Person Education Code | Education code of the person. | Yes | `123456` | Text | | Credential | Person Gender | Gender of the person. | Yes | `Male` | Text | | Credential | Person Personal No | The personal number of the person. | Yes | `123456` | Text | | Credential | Person Photo 1 | Person's photo, base64 encoded. | Yes | `base64` | Base64 encoded image | | Credential | Person Photo 2 | Alternative person photo, base64 encoded. | Yes | `base64` | Base64 encoded image | | Credential | Person Pin | Person's PIN | Yes | `1234` | Text | | Credential | Person Signature | Person's signature, base64 encoded. | Yes | `base64` | Base64 encoded image | | Credential | Person Title | The title of the person. | Yes | `CEO` | Text | | Credential | Range 1-3 Formula 1 | Calculated result of configured formula | No | `0EAA25CE` | Text | | Credential | Range 1-3 Formula 2 | Calculated result of configured formula | No | `1EAA2511` | Text | | Credential | Range 1-3 Formula 3 | Calculated result of configured formula | No | `25ECBA32` | Text | | Credential | Range 1-3 Full Sequence | The full sequence of the number range. | No | `00042123409` | Text | | Credential | Range 1-3 Prefix | The prefix of the number range. | No | `000` | Text | | Credential | Range 1-3 Sequence | The sequence of the number range. | No | `1234` | Text | | Credential | Range 1-3 Site Code | The site code of the number range. | No | `42` | Text | | Credential | Range 1-3 Suffix | The suffix of the number range. | No | `9` | Text | | Credential | Range 1-3 Version Number | The version number of the number range. | No | `1` | Text | | Credential | Template Formula 1-3 | Calculated result of configured formula. | No | `00045145` | Text | | Credential | Requester Email | The email of the requester. | No | `requester@yourcompany.inc` | Text | | Credential | Requester First Name | The first name of the requester. | No | `John` | Text | | Credential | Requester Last Name | The last name of the requester. | No | `Doe` | Text | | Credential | Requester Phone | The phone number of the requester. | No | `123456` | Text | | Credential | Tenant Id | The unique identifier of the Tenant. | No | `66e1ad73bd756adad71c632c` | Text | | Order | Id | The unique identifier of the Order. | No | `66e1ad73bd756adad71c632c` | Text | | Order | Status | Current status of the Order. | No | `Active` | Text | | Order | Order Number | The order number. | No | `123456` | Text | | Order | Order Placed | The date the order was placed. | No | `2022-12-31` | Date | | Order | Order Reference | The reference of the order. | Yes | `123456` | Text | | Order | Contact Email | The email of the contact person. | Yes | `someperson@yourcompany.inc` | Text | | Order | Contact Phone | The phone number of the contact person. | Yes | `+4744444444` | Text | | Order | User Id | The unique identifier of the User. | No | `66e1ad73bd756adad71c632c` | Text | | Order | User Email | The email of the User. | No | `someuser@yourcompany.inc` | Text | | Tenant | Id | The unique identifier of the Tenant. | No | `66e1ad73bd756adad71c632c` | Text | | Tenant | Number | The number of the Tenant. | No | `123456` | Text | | Tenant | Name | The name of the Tenant. | No | `Your Company Inc.` | Text | | Tenant | External Id | The external identifier of the Tenant. | No | `123456` | Text | | Tenant | Contact Email | The email of the contact person. | No | `someadmin@yourcompany.inc` | Text | | Template | Id | The unique identifier of the Template. | No | `66e1ad73bd756adad71c632c` | Text | | Template | Name | The name of the Template. | No | `Your Template` | Text | \* The `Card Valid Until Date` field can be either manually entered or automatically populated depending on the Credential Template settings. ## Data Types ### Text Text data type will transfer the data as plain text. ### Date Date data type will transfer the data as a date. The date format will be in a `YYYY-MM-DD` format. ### Base64 Encoded Image Base64 encoding is a method of converting binary data, such as an image, into a string format. This is useful for transmitting image data in text-based formats, such as JSON or HTML. When data is encoded in Base64, it represents the binary data as a series of ASCII characters. This makes it possible to include images in formats that otherwise only support text. In this context, Base64-encoded images are used to transfer picture data, which can then be decoded back into the original image format by the receiving system. --- ## Setting up Azure App Service Hybrid Connection to Your SQL Server Use Azure App Service Hybrid Connections to let Breeze (running in Azure App Service) securely reach your on‑premises or private‑network SQL Server without opening inbound firewall ports. Hybrid Connections uses Azure Relay over outbound TLS to create a private TCP tunnel to a specific host and port in your network. ::::info Customer Guide: This guide explains how to install and configure the Hybrid Connection Manager (HCM) in your environment so our cloud application can securely connect to your SQL Server without opening your network to the internet. :::: --- ## 1. What is the Hybrid Connection Manager? **Purpose**: Acts as a secure bridge between your SQL Server and our cloud service. How it works: - HCM runs as a Windows service in your network. - It creates a secure outbound connection (TLS 443) to Microsoft Azure Relay. - Our application connects to the same Relay. - The Relay forwards only the SQL traffic to your SQL Server. ::::note Important: The connection is outbound only. We cannot access your network in any other way. :::: ![Hybrid Connection Manager](./_images/image.png) --- ## 2. Prerequisites on your side Windows Server (VM or physical) that: - Is always on and has network access to your SQL Server - Can reach the internet over TCP 443 (outbound) Your SQL Server must: - Listen on a fixed TCP port (commonly 1433) - Allow login with the credentials we have agreed upon (SQL login only) - Use TLS 1.2+ with a publicly trusted CA certificate; CN/SAN must match the host name used by the connection Other requirements: - DNS resolution in your network for the SQL Server host name ::::warning Hybrid Connections supports TCP to a single host and port. It does not carry UDP. Named instances that rely on SQL Browser (UDP 1434) are not supported unless the SQL instance listens on a known fixed TCP port. :::: --- ## 3. Install Hybrid Connection Manager (HCM) 1. Download the latest HCM installer from Microsoft: [Hybrid Connection Manager download](https://learn.microsoft.com/nb-no/azure/app-service/app-service-hybrid-connections?tabs=windows#hybrid-connection-manager) 2. Run the installer on the chosen Windows Server 3. Open the Hybrid Connection Manager UI (Start menu) 4. Confirm the "Hybrid Connection Manager Service" is running (set Startup type to Automatic) --- ## 4. Add the Hybrid Connection We will provide you with: - Hybrid Connection Name (for example, `hc-customer-sql01`) - Listener SAS Key (shared access key) or full connection string Steps: 1. In the HCM UI, click "Add a new Hybrid Connection" 2. Paste the connection string or SAS key we provided 3. Save 4. The connection should now appear in the list --- ## 5. Verify the connection - In the HCM UI, the connection should show as "Connected" - If it shows "Not connected": - Ensure the server has outbound internet access on TCP 443 to `*.servicebus.windows.net` - Confirm the SQL Server host/port is reachable from the HCM machine --- ## 6. Security notes - No inbound firewall changes are needed - The SAS key we provide is scoped only to this specific Hybrid Connection - We can rotate keys at any time if needed - You control the SQL Server, its firewall, and its logins — we cannot access anything else in your network - TLS 1.2+ must be used with a certificate from a publicly trusted CA (private CAs and self‑signed certificates are not supported) - Only SQL logins are supported --- ## 7. Ongoing maintenance - Keep the Windows Server hosting HCM always running - Ensure the Hybrid Connection Manager Service is set to Automatic Start - Monitor Windows Event Logs under: Applications and Services Logs → Microsoft Web Apps → HybridConnectionManager - Apply Microsoft updates to the server as usual --- ## ✅ Summary By installing HCM and adding the connection we provide, you enable a secure, outbound‑only tunnel so our cloud service can write to your SQL database. Nothing else in your network is exposed. --- ## Microsoft documentation - Azure App Service Hybrid Connections (overview and setup): [Microsoft Learn](https://learn.microsoft.com/azure/app-service/app-service-hybrid-connections) - Install the Hybrid Connection Manager (HCM): [Microsoft Learn – Install HCM](https://learn.microsoft.com/azure/app-service/app-service-hybrid-connections#install-the-hybrid-connection-manager) - Hybrid Connections troubleshooting: [Microsoft Learn – Troubleshooting](https://learn.microsoft.com/azure/app-service/app-service-hybrid-connections#troubleshooting) --- ## Next steps - Return to your AMR SQL Sync template and complete mapping and activation - See also: `docs/integrations/amr/sql-syncronization.md` --- ## Connectivity and Security for AMR SQL This guide defines the common security and connectivity requirements for AMR SQL integrations (SQL Synchronization and SQL Transfer). --- ## Security requirements - Transport encryption: Use TLS 1.2+ for all database connections. The SQL Server must present a certificate issued by a publicly trusted CA; private CAs and self‑signed certificates are not supported. The host name must match the certificate CN/SAN. - Authentication: Only SQL logins are supported. Windows/AD or certificate‑based authentication methods are not supported. - Least privilege: Use a dedicated SQL login with the minimum required permissions. Grant DDL permissions only if using schema management modes that create or alter tables. - Secrets handling: Passwords are write‑only in the UI and are never included in emails or logs. - Data at rest: For Breeze‑hosted SQL, platform encryption (for example, TDE on Azure SQL) protects data at rest. For customer‑hosted SQL, enable TDE or equivalent disk/database encryption per your policy. --- ## Network connectivity options (Option A) Preferred options for customer‑hosted SQL: - Azure App Service Hybrid Connections (recommended): Outbound‑only TLS tunnel from your network to Azure Relay. No inbound firewall openings are required. See: [Setting up Azure App Service Hybrid Connection to Your SQL Server](/docs/integrations/amr/connectivity/azure-app-service-hybrid-connections). - Site‑to‑site VPN or equivalent: Private network link from Azure to your environment without exposing SQL to the internet. ![Option A](./_images/option_a.png) If private options are not possible (**not recommended**), you may allow public connectivity with strict controls: - Open inbound TCP 1433 (or your fixed SQL port) only from Breeze egress IPs - Prefer a fixed port/instance (named instances require additional ports). If using named instances with SQL Browser, also allow UDP 1434 and the instance's dynamic TCP port - Enforce TLS 1.2+ with a publicly trusted CA certificate - Allow DNS resolution for the SQL host FQDN - Contact Breeze Support for current Breeze egress IPs to allowlist - Do not expose SQL Server broadly to the internet; restrict to the minimal required IPs and ports --- ## Breeze‑hosted SQL (Option B) - Prefer Private Endpoint when the consumer of data runs in Azure; otherwise, we allowlist your public IP(s) on the SQL firewall - TLS 1.2+ is required; certificates chain to publicly trusted roots - Data at rest is protected with platform encryption (for example, TDE on Azure SQL) - We provision per‑tenant SQL logins with least‑privilege access - Your network needs outbound TCP 1433 to the provided SQL FQDN (or to the Private Endpoint via your private network) Operational notes: - Breeze provisions and maintains the SQL instance. Storage and performance sizing are agreed during onboarding and billed as an add‑on - Access credentials are provided securely and can be rotated on request ![Option B](./_images/option_b.png) --- ## Troubleshooting highlights - TLS/certificate errors: Ensure the certificate chains to a publicly trusted root and the host name matches the certificate CN/SAN - Connectivity: For Hybrid Connections, verify outbound TCP 443 and HCM status = Connected; for public connectivity, verify firewall allowlisting and fixed port - Permissions: Confirm the SQL login has required rights and matches schema management mode --- ## AMR File Synchronization File synchronization is a method that allows you to transfer Credential data to third-party systems using an Azure Storage account. This approach is particularly useful when the receiving system supports file-based data transfers, making it a seamless way to move Credential information. To learn more about AMR and other methods of transferring Credential data to third-party systems, visit the [Access Management Router (AMR)](/docs/integrations/amr). --- ## Prerequisites :::info - **Availability**: This feature is available only for Enterprise plans. Contact your Breeze representative or dealer to explore available Enterprise plan options. ::: :::note[Required roles] **Required roles**: - `System Administrator` - `Data Exporter` These roles are necessary to perform the file synchronization configuration. If you do not hold these roles, please contact someone in your organization who does. ::: Before starting the AMR File Synchronization setup, make sure you meet the following prerequisites: - Access to the **Breeze Admin Portal**. - An **Azure Storage account** that includes a **File Share** for storing the synchronized data. - A clear understanding of **which data fields** you want to transfer to the third-party system. **Note**: If you don’t have an Azure Storage account set up, the Breeze Team can assist in providing one as a service. Reach out to Breeze Support for more information. ## Azure Storage Account Configuration To use file synchronization, you need to configure your Azure Storage account. The account must have a **File Share** set up to receive the synchronized data. If you are unfamiliar with configuring Azure Storage, refer to the official [Microsoft Azure Storage documentation](https://docs.microsoft.com/en-us/azure/storage/). Before moving forward with the AMR synchronization steps, ensure you have the following details: - **Storage account name** - **File Share name** - **Storage account access key or secret** - **File path and name** for the file that will store the synchronized data. ## File Format The AMR synchronization process uses a **CSV file** format to transfer data. This CSV file is created by the AMR service during the synchronization process and should **not exist** prior to synchronization. ### Key characteristics of the file: - **File type**: CSV (Comma-Separated Values) - **Column separator**: Semicolon (`;`) - **Header row**: The first row of the file contains the column headers that identify the data fields. **Important**: The format of the file should never be modified, as the AMR service relies on the exact format to process the data correctly. You can remove rows (e.g., individual credentials), but changing the structure of the file could disrupt the synchronization process. For guidance on adjusting the content of the file, refer to the [Modify File Content](#modify-file-content) section. :::warning Do not alter the file format. Doing so could cause the synchronization process to fail. ::: ## Modify File Content If you need to adjust which records are synchronized, you can safely modify the CSV file content with the following constraints: - Remove entire rows to exclude specific Credentials from being processed. - Do not add, remove, rename, or reorder columns. The header row and column order must exactly match the AMR configuration. - Keep the semicolon (;) delimiter unchanged. - If images are included as Base64 columns, ensure values are valid Base64 without line breaks. - If images are synchronized as separate files, you may delete specific image files; depending on settings, they can be recreated on the next sync. If you later change field mappings in AMR, ensure the CSV columns and order match the new configuration. For details, see [Field Mappings](#field-mappings). ## Available Data Fields When setting up the AMR File Synchronization, you can choose which data fields to include in the CSV file. You can find a complete list of available fields here: [Available Data Fields](/docs/integrations/amr/available-data-fields). :::warning Carefully evaluate the fields you select to ensure they meet the long-term needs of the third-party system. Once synchronization starts, altering the configuration could require a migration of existing data. Additionally, export only the necessary data fields to avoid cluttering the system with irrelevant information. ::: ## Images in File Synchronization ### Option 1: Images as Separate Files The AMR File Synchronization process can include images as individual files within the Azure File Share. This feature needs to be enabled in the AMR configuration (see [Sync Images](#sync-images)). If enabled, images are stored in a folder named `images` within the Azure File Share. For each credential, the following images will be created (if available): - **PersonPhoto1**: Saved as `PersonPhoto1_.jpg`. - **PersonPhoto2**: Saved as `PersonPhoto2_.jpg`. - **PersonSignature**: Saved as `PersonSignature_.jpg`. - **Credential Front Image**: Saved as `Front_.jpg` (a full-size image of the front of the credential/card). - **Credential Back Image**: Saved as `Back_.jpg` (a full-size image of the back of the credential/card). If an image is not available, the corresponding file will not be created. ### Option 2: Images as Base64 Encoded Strings Alternatively, images can be included directly in the CSV file as Base64 encoded strings. This method is useful when embedding images within the data file itself, rather than storing them separately. In this case, the column header will use the image field name (e.g., `personPhoto1`), and the image data will be represented as a Base64 encoded string within the CSV. ## Triggers for File Synchronization AMR provides built-in triggers that automatically synchronize data based on changes in the status of a Credential. These events activate the synchronization and transfer updated Credential data to the third-party system. The triggers include: - **Credential produced** (triggered if AMR is set to "Automatic Sync") - **Credential activated** - **Credential deactivated** - **Credential deleted** For example, when a credential is activated, the AMR will automatically sync the associated data with the third-party system. ## Create a New AMR File Synchronization Configuration To set up AMR File Synchronization, follow these steps: 1. **Access the Tenant**: Log into the Breeze portal and navigate to the `Tenant` where you want to configure file synchronization. 2. **Go to Templates**: In the left-side menu, select `Templates`. 3. **Open AMR Transfer Templates**: Click the `Go to AMR Transfer Templates` button. 4. **Create a New Template**: Click on the `Create New AMR Transfer Template` button. 5. **Select the AMR Transfer Type**: Choose `FILE_SYNC` as the transfer type. 6. **Complete the Form**: Fill in the required fields with the configuration details (see next section for details). 7. **Test Connection**: Use the `Test Connection` button to confirm that the Azure Storage account is correctly set up. 8. **Save**: Once everything is configured, click `Save` to create the AMR File Synchronization configuration. After saving, the configuration will be created but not yet ready for use. Continue with the [Configure AMR File Synchronization](#configuring-amr-file-synchronization) section to finalize the setup. ### Settings Details | **Setting** | **Description** | **Example Value** | | -------------------- | ------------------------------------------------------- | -------------------------------- | | **Name** | The name of the AMR File Synchronization configuration. | `Access Control System Transfer` | | **Client ID** | The name of the Azure Storage account. | `breezestorage` | | **Client Secret** | The access key/secret for the Azure Storage account. | `ueJVIw0XXXXXXXXfcQB3w==` | | **Azure Share Name** | The name of the File Share in Azure. | `breeze-share` | | **File Name** | The file name used for synchronization. | `access-control.csv` | ## Configuring AMR File Synchronization :::note[Required roles] **Roles required**: - `System Administrator` - `Data Exporter` - You need both of these roles to perform the following configuration steps. If you don't have these roles, please contact your system administrator. ::: Once the AMR File Synchronization configuration has been created, it needs to be customized to fit your specific requirements. To do this, follow these steps: 1. Locate the **AMR File Synchronization configuration** in the list of configurations. 2. Click the **Edit** button next to the configuration to open the settings dialog. 3. Adjust the settings according to your needs. A description of each setting is provided below. 4. After making your changes, be sure to click the **Save** button to apply them. ### Key Configuration Settings #### Template Name You can change the **name** of the AMR File Synchronization configuration. This name should reflect the purpose or destination of the synchronization to easily identify it later (e.g., “Access Control Sync to Azure”). #### Report Incidents To To receive email notifications in case the synchronization process encounters errors or fails, you can add an email address here. This is particularly useful for monitoring and troubleshooting. ### General Settings | **Setting** | **Description** | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** | Toggle whether the configuration is active. Only active configurations will be available for selection when setting up an AMR on a Credential Template. | | [**Activation method**](#activation-method) | Defines how the AMR sync for a Credential will be triggered. You can choose between **Automatic sync** and **Manual sync**. | | [**Sync images**](#sync-images) | Specifies whether images should be included in the synchronization. The available options are **Always**, **One time**, or **Never**. | | [**Allowed for sub-tenants**](#allowed-for-sub-tenants) | Determines if the AMR configuration is accessible to sub-tenants under the current Tenant. | #### Activation Method This setting controls how the synchronization is triggered for a Credential: - **Automatic sync**: The synchronization will start automatically as soon as a Credential is produced. No manual intervention is needed. - **Manual sync**: The synchronization must be manually initiated from the Credential view before data is transferred to the third-party system. Choose the option that best fits your workflow—automatic syncs are ideal for hands-free updates, while manual syncs offer more control. #### Sync Images The **Sync images** option determines if images (such as photos and signatures) are included in the synchronization process. If this option is enabled, the images will be transferred to the third-party system as files in the Azure storage. There are three options to choose from: - **Always**: Images will be synchronized during every sync, ensuring that they are kept up-to-date with every data transfer. - **One time**: Images will be synchronized only during the first sync. Subsequent syncs will not transfer or update images. - **Never**: No images will be included in the synchronization. Images that may be transferred (if available) include: - **PersonPhoto1** - **PersonPhoto2** - **PersonSignature** - **Credential front image** (a full-size image of the front of the credential/card) - **Credential back image** (a full-size image of the back of the credential/card) #### Allowed for Sub-tenants If this option is enabled, the AMR File Synchronization configuration will be made available for all sub-tenants under the current Tenant, provided they share the same System Domain. This is useful when multiple sub-tenants require the same synchronization setup, streamlining the process across different parts of your organization. ### Storage Settings If needed, you can modify the Azure Storage account settings for the file synchronization. To do so: - Click the **Edit** button to open the settings dialog. - Make the necessary changes (such as updating the storage account key or share name). For more details on the storage settings, refer to the [Create a New AMR File Synchronization Configuration](#create-a-new-amr-file-synchronization-configuration) section. ### Field Mappings :::warning Changes to field mappings should be made with caution. Adjusting field mappings may disrupt the synchronization process if not handled correctly. If you add, rearrange, or remove fields from an active AMR configuration, you may need to manually update the corresponding file in the Azure Storage account to match the new field mappings. The sync will fail if the file and mappings are not aligned. ::: In this section, you can define which data fields will be included in the CSV file used for synchronization. 1. **Open the Field Selection Dialog**: Click the **Change settings** button to open the field selection window. 2. **Select Data Fields**: Choose the source object and the specific fields you want to include in the CSV file, then move them to the `Selected` column. 3. **Rearrange Fields**: Use the up/down arrows to rearrange the order of the selected fields. :::info The order of the fields in the CSV file will match the order in the `Selected` column. Make sure the order aligns with the expectations of the third-party system. ::: 4. **Save Changes**: Click **Save** to apply the field mappings. For a complete list of available data fields, refer to [Available Data Fields](/docs/integrations/amr/available-data-fields). --- ## AMR File Transfer File transfer is a method that allows you to transfer Credential data to third-party systems using an Azure Storage account. This approach is particularly useful when the receiving system supports file-based data transfers, making it a seamless way to move Credential information as a one-time transfer. To learn more about AMR and other methods of transferring Credential data to third-party systems, visit the [Access Management Router (AMR)](/docs/integrations/amr). --- ## Prerequisites :::info - **Availability**: This feature is available only for Enterprise plans. Contact your Breeze representative or dealer to explore available Enterprise plan options. ::: :::note[Required roles] **Required roles**: - `System Administrator` - `Data Exporter` These roles are necessary to perform the file transfer configuration. If you do not hold these roles, please contact someone in your organization who does. ::: Before starting the AMR File Transfer setup, make sure you meet the following prerequisites: - Access to the **Breeze Admin Portal**. - An **Azure Storage account** that includes a **File Share** for storing the transferred data. - A clear understanding of **which data fields** you want to transfer to the third-party system. **Note**: If you don't have an Azure Storage account set up, the Breeze Team can assist in providing one as a service. Reach out to Breeze Support for more information. ## Azure Storage Account Configuration To use file transfer, you need to configure your Azure Storage account. The account must have a **File Share** set up to receive the transferred data. If you are unfamiliar with configuring Azure Storage, refer to the official [Microsoft Azure Storage documentation](https://docs.microsoft.com/en-us/azure/storage/). Before moving forward with the AMR transfer steps, ensure you have the following details: - **Storage account name** - **File Share name** - **Storage account access key or secret** - **File path and name** for the file that will store the transferred data. ## File Format The AMR transfer process uses a **CSV file** format to transfer data. This CSV file is created by the AMR service during the transfer process and should **not exist** prior to transfer. ### Key characteristics of the file: - **File type**: CSV (Comma-Separated Values) - **Column separator**: Semicolon (`;`) - **Header row**: The first row of the file contains the column headers that identify the data fields. **Important**: The format of the file should never be modified, as the AMR service relies on the exact format to process the data correctly. You can remove rows (e.g., individual credentials), but changing the structure of the file could disrupt the transfer process. :::warning Do not alter the file format. Doing so could cause the transfer process to fail. ::: ## Available Data Fields When setting up the AMR File Transfer, you can choose which data fields to include in the CSV file. You can find a complete list of available fields here: [Available Data Fields](/docs/integrations/amr/available-data-fields). :::warning Carefully evaluate the fields you select to ensure they meet the needs of the third-party system. Export only the necessary data fields to avoid cluttering the system with irrelevant information. ::: ## Images in File Transfer ### Option 1: Images as Separate Files The AMR File Transfer process can include images as individual files within the Azure File Share. This feature needs to be enabled in the AMR configuration (see [Include Images](#include-images)). If enabled, images are stored in a folder named `images` within the Azure File Share. For each credential, the following images will be created (if available): - **PersonPhoto1**: Saved as `PersonPhoto1_.jpg`. - **PersonPhoto2**: Saved as `PersonPhoto2_.jpg`. - **PersonSignature**: Saved as `PersonSignature_.jpg`. - **Credential Front Image**: Saved as `Front_.jpg` (a full-size image of the front of the credential/card). - **Credential Back Image**: Saved as `Back_.jpg` (a full-size image of the back of the credential/card). If an image is not available, the corresponding file will not be created. ### Option 2: Images as Base64 Encoded Strings Alternatively, images can be included directly in the CSV file as Base64 encoded strings. This method is useful when embedding images within the data file itself, rather than storing them separately. In this case, the column header will use the image field name (e.g., `personPhoto1`), and the image data will be represented as a Base64 encoded string within the CSV. ## Transfer Trigger The AMR File Transfer is designed as a one-time transfer that automatically triggers when a Credential's status changes to `produced`. This ensures that the data is transferred exactly once at the appropriate moment in the Credential lifecycle. ## Create a New AMR File Transfer Configuration To set up AMR File Transfer, follow these steps: 1. **Access the Tenant**: Log into the Breeze portal and navigate to the `Tenant` where you want to configure file transfer. 2. **Go to Templates**: In the left-side menu, select `Templates`. 3. **Open AMR Transfer Templates**: Click the `Go to AMR Transfer Templates` button. 4. **Create a New Template**: Click on the `Create New AMR Transfer Template` button. 5. **Select the AMR Transfer Type**: Choose `FILE_TRANSFER` as the transfer type. 6. **Complete the Form**: Fill in the required fields with the configuration details (see next section for details). 7. **Test Connection**: Use the `Test Connection` button to confirm that the Azure Storage account is correctly set up. 8. **Save**: Once everything is configured, click `Save` to create the AMR File Transfer configuration. After saving, the configuration will be created but not yet ready for use. Continue with the [Configure AMR File Transfer](#configuring-amr-file-transfer) section to finalize the setup. ### Settings Details | **Setting** | **Description** | **Example Value** | | -------------------- | ---------------------------------------------------- | -------------------------------- | | **Name** | The name of the AMR File Transfer configuration. | `Access Control System Transfer` | | **Client ID** | The name of the Azure Storage account. | `breezestorage` | | **Client Secret** | The access key/secret for the Azure Storage account. | `ueJVIw0XXXXXXXXfcQB3w==` | | **Azure Share Name** | The name of the File Share in Azure. | `breeze-share` | | **File Name** | The file name used for transfer. | `access-control.csv` | ## Configuring AMR File Transfer :::note[Required roles] **Roles required**: - `System Administrator` - `Data Exporter` - You need both of these roles to perform the following configuration steps. If you don't have these roles, please contact your system administrator. ::: Once the AMR File Transfer configuration has been created, it needs to be customized to fit your specific requirements. To do this, follow these steps: 1. Locate the **AMR File Transfer configuration** in the list of configurations. 2. Click the **Edit** button next to the configuration to open the settings dialog. 3. Adjust the settings according to your needs. A description of each setting is provided below. 4. After making your changes, be sure to click the **Save** button to apply them. ### Key Configuration Settings #### Template Name You can change the **name** of the AMR File Transfer configuration. This name should reflect the purpose or destination of the transfer to easily identify it later (e.g., "Access Control Transfer to Azure"). #### Report Incidents To To receive email notifications in case the transfer process encounters errors or fails, you can add an email address here. This is particularly useful for monitoring and troubleshooting. ### General Settings | **Setting** | **Description** | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** | Toggle whether the configuration is active. Only active configurations will be available for selection when setting up an AMR on a Credential Template. | | [**Include images**](#include-images) | Specifies whether images should be included in the transfer. The available options are **Yes** or **No**. | | [**Allowed for sub-tenants**](#allowed-for-sub-tenants) | Determines if the AMR configuration is accessible to sub-tenants under the current Tenant. | #### Include Images The **Include images** option determines if images (such as photos and signatures) are included in the transfer process. If this option is enabled, the images will be transferred to the third-party system as files in the Azure storage. There are two options to choose from: - **Yes**: Images will be included in the transfer. - **No**: No images will be included in the transfer. Images that may be transferred (if available) include: - **PersonPhoto1** - **PersonPhoto2** - **PersonSignature** - **Credential front image** (a full-size image of the front of the credential/card) - **Credential back image** (a full-size image of the back of the credential/card) #### Allowed for Sub-tenants If this option is enabled, the AMR File Transfer configuration will be made available for all sub-tenants under the current Tenant, provided they share the same System Domain. This is useful when multiple sub-tenants require the same transfer setup, streamlining the process across different parts of your organization. ### Storage Settings If needed, you can modify the Azure Storage account settings for the file transfer. To do so: - Click the **Edit** button to open the settings dialog. - Make the necessary changes (such as updating the storage account key or share name). For more details on the storage settings, refer to the [Create a New AMR File Transfer Configuration](#create-a-new-amr-file-transfer-configuration) section. ### Field Mappings :::warning Changes to field mappings should be made with caution. Adjusting field mappings may disrupt the transfer process if not handled correctly. ::: In this section, you can define which data fields will be included in the CSV file used for transfer. 1. **Open the Field Selection Dialog**: Click the **Change settings** button to open the field selection window. 2. **Select Data Fields**: Choose the source object and the specific fields you want to include in the CSV file, then move them to the `Selected` column. 3. **Rearrange Fields**: Use the up/down arrows to rearrange the order of the selected fields. :::info The order of the fields in the CSV file will match the order in the `Selected` column. Make sure the order aligns with the expectations of the third-party system. ::: 4. **Save Changes**: Click **Save** to apply the field mappings. For a complete list of available data fields, refer to [Available Data Fields](/docs/integrations/amr/available-data-fields). --- ## Access Management Router (AMR) :::tip Imagine this Imagine a new employee’s card being produced and—before they reach the front door—their access is already live in every system that matters. ::: The Access Management Router (AMR) moves Credential data from Breeze to your ecosystem automatically and securely. It connects Breeze to access control systems, HR/ERP platforms, and custom applications so the right people get the right access—on time and with minimal manual work. What AMR delivers: - **Speed**: Data flows as soon as a Credential is produced, activated, deactivated, or deleted. - **Choice**: Multiple delivery methods so you can integrate with file-based systems, databases, or APIs. - **Control**: Field-level mapping, tenant-aware incident notifications, and safe retry flows. Popular use cases: - **Access control onboarding**: Send new employee card data to your physical access control system (PACS) the moment a card is produced. - **Badge lifecycle updates**: Keep status in sync when a card is activated, deactivated, or deleted. - **Directory/HR alignment**: Mirror key identity attributes (names, photos, identifiers) to downstream systems. - **Temporary or visitor cards**: Push one-time records to a database for short-lived access. AMR methods you can use today: - **File Synchronization (Azure File Share)**: Continuous updates written to a CSV in your file share. Ideal when a third‑party system imports from a watched file. - **File Transfer (Azure File Share)**: One‑time CSV (and optional images) created when a Credential is produced. - **SQL Synchronization (MSSQL)**: Continuous updates written to a Microsoft SQL Server table with simple field‑to‑column mapping. - **SQL Transfer (MSSQL)**: One‑time push to a SQL table immediately after production. - **Webhooks (HTTP/HTTPS)**: Coming soon. How it works (at a glance): - Breeze fires built‑in triggers on key Credential events. - AMR formats the data according to your mapping and chosen method. - The data is delivered to the target (file share, SQL table, or soon an API endpoint). - If something goes wrong, recipients you choose are notified with batched incident emails. Choose the right method: - **Need ongoing updates?** Use File Synchronization or SQL Synchronization. - **Need a one‑time export per card?** Use File Transfer or SQL Transfer. - **Have a real‑time API?** Webhooks will be a great fit when available. To learn more or set up AMR, jump to the method that fits your target system: - [File Synchronization](/docs/integrations/amr/file-synchronization) - [File Transfer](/docs/integrations/amr/file-transfer) - [SQL Synchronization (MSSQL)](/docs/integrations/amr/sql-syncronization) - [SQL Transfer (MSSQL)](/docs/integrations/amr/sql-transfer) - [Webhooks](/docs/integrations/amr/webhooks) (Coming Soon) These methods are designed for low‑level integration to move Credential data into third‑party systems. For advanced access capabilities (rules, decisions, real‑time authorization), see the [Breeze Access Module](/docs/access). ::::info **Availability**: AMR is available for Enterprise plans only. Contact your dealer or Breeze representative to learn more about our Enterprise plans. :::: --- ## AMR SQL Synchronization AMR SQL Synchronization lets you keep an external Microsoft SQL Server (MSSQL) table up to date with Credential data from Breeze. Instead of exporting files, data is written directly to your SQL database whenever relevant changes happen, so connected systems always have the latest information. To learn more about AMR and other ways to move Credential data to third‑party systems, see the [Access Management Router (AMR)](/docs/integrations/amr). --- ## Prerequisites ::::info - **Availability**: This feature is available for Enterprise plans. Contact your Breeze representative or dealer for options. ::: ::::note[Required roles] **Required roles**: - `System Administrator` - `Data Exporter` You need these roles to configure and manage AMR SQL Synchronization. :::: Before you start: - Access to the **Breeze Admin Portal** - Access to a **Microsoft SQL Server** instance and credentials - Know where the data should be stored: database, optional schema, and table name - Your Domain/Tenant must have the **AMR SQL** feature enabled --- ## MSSQL requirements and permissions Have these connection details ready: - Host (DNS or IP) and Port (default `1433`) - Database name - Username and Password (password is write‑only in the UI) - TLS encryption (TLS 1.2+ required) using a publicly trusted CA certificate (private CAs and self‑signed certificates are not supported) Permissions depend on your schema management choice (see below): - `none`: INSERT/UPDATE on the target table - `create`: permission to create the target table if missing - `create_update`: permissions to create the table and add missing columns :::::note Only SQL logins are supported. Windows/AD or certificate‑based authentication methods are not supported. ::::: --- ## Available data fields and mapping Use the built‑in Mapping editor to choose Breeze fields and assign their destination SQL columns. You do not enter mapping strings manually. How it works: 1. Open the Mapping editor from the template. 2. Pick a Breeze field from the dropdown list. 3. Type the SQL column name you want to write to, then click Add field. 4. Repeat for all needed fields. Optionally enable a dedicated SQL timestamp column to store the last sync time. Guidelines: - Include only the fields required by your downstream system. - SQL column names must be valid identifiers (start with a letter/underscore; contain only letters, numbers, underscores; max 128 chars). - Avoid reserved SQL keywords as column names. See also: [Mapping settings](#mapping-settings) and [Available Data Fields](/docs/integrations/amr/available-data-fields). --- ## Triggers for SQL synchronization AMR automatically syncs when Credential status changes: - Credential produced (if activation is set to Automatic) - Credential activated - Credential deactivated - Credential deleted or replaced (final update and stop) In addition, a periodic fallback update runs daily to help ensure consistency. > Note: If the template’s Activation method is set to Automatic, the Credential will be activated immediately after production. The activation event also triggers a sync. --- ## Create a new AMR SQL Synchronization configuration 1. Go to your **Tenant** in the Breeze Admin Portal 2. Open **Templates** → **AMR Transfer Templates** 3. Click **Create New AMR Transfer Template** 4. Select the AMR Transfer Type: **SQL_SYNC** and fill in the initial SQL settings. See: [SQL connection settings](#sql-connection-settings) and [Target table](#target-table). 5. Click **Test Connection**. You must get a success message to proceed. See: [Test connection](#test-connection). 6. Click **Save**. The configuration drawer opens for further settings. 7. Add incident recipients (recommended) so you’re notified if something goes wrong. See: [Incident notifications](#incident-notifications-report-incidents-to). 8. Configure field mappings: choose Breeze fields and assign SQL columns. Optionally enable a timestamp column. See: [Available data fields and mapping](#available-data-fields-and-mapping) and [Mapping settings](#mapping-settings). 9. Set other options and activation method, then save. See: [Key configuration settings](#key-configuration-settings) and [Activation method](#activation-method). 10. You can change SQL settings later if needed. See: [SQL connection settings](#sql-connection-settings). After these steps, your template is ready. Associate it with Credential Templates as needed. --- ## Configuring AMR SQL Synchronization ::::note[Required roles] You must have both `System Administrator` and `Data Exporter` to make these changes. :::: ### Key configuration settings | Setting | Description | | ----------------------- | --------------------------------------------------------- | | Name | Human‑readable name for the configuration | | Active | Only active templates can be used by Credential Templates | | Activation method | Automatic or Manual | | Allowed for sub-tenants | Make available to sub‑tenants on the same System Domain | | Report Incidents To | Email address(es) to receive incident notifications | #### Activation method - **Automatic sync**: sync starts automatically as soon as a Credential is produced - **Manual sync**: sync must be initiated from the Credential or Template UI ### SQL connection settings | Setting | Description | Example | | -------- | ------------------------------------- | ------------------ | | SQL Type | RDBMS type | mssql | | Host | DNS or IP of the SQL Server | sql.mycorp.local | | Port | TCP port | 1433 | | Database | Database name | access_integration | | Username | SQL login user | breeze_writer | | Password | SQL login password (write‑only in UI) | •••••• | | SSL | Encrypt connection (true/false) | true | ### Target table | Setting | Description | Example | | ----------------- | ----------------- | --------------- | | Schema (optional) | Schema name | dbo | | Table | Target table name | amr_credentials | ### Schema management (optional) | Mode | Description | | ------------- | ---------------------------------------------- | | none | No DDL changes; table and columns must exist | | create | Create target table if missing | | create_update | Create table and add missing columns if needed | ::::warning Use schema management with care in production environments, as it can create or alter tables. :::: ### Mapping settings 1. Open the **Mapping** editor 2. Pick Breeze fields and assign SQL columns 3. Reorder mappings as needed 4. Save when validation passes ::::info If you add, remove, or reorder mapped fields on an active configuration, ensure the target table still matches the mapping (especially in `none` mode). Mismatches will cause sync failures. :::: ### Test connection Use **Test Connection** to verify the SQL connectivity (basic health check such as `SELECT 1`). Fix any errors before activating. --- ## Security & Networking ::::info For complete security and connectivity requirements (TLS 1.2+ with publicly trusted CA, SQL logins only, least‑privilege access, and recommended private connectivity), see: - [Connectivity and Security for AMR SQL](/docs/integrations/amr/connectivity/sql-security-networking) - Recommended for Option A: [Setting up Azure App Service Hybrid Connection to Your SQL Server](/docs/integrations/amr/connectivity/azure-app-service-hybrid-connections) :::: --- ## Incident notifications (Report incidents to) Add one or more email recipients under "Report incidents to" to be informed about failures and other important events for this AMR template. What you’ll receive: - Emails when the system detects repeated errors during push/sync activities for this template. - Messages are batched within a short window to avoid inbox spam. - Each email groups identical errors together and shows a single sample technical detail with a tidy list of affected Credentials (with tenant‑aware links). - If a Credential later succeeds before the email is sent, it is removed from the batch. If all items recover, no email is sent. - Emails never include sensitive secrets such as passwords. Good practices: - Use a shared mailbox or distribution list for on‑call/ops teams. - Keep recipients scoped to people responsible for integrations. - Review incidents and resolve underlying mapping, connectivity, or permission issues. ## Troubleshooting - **Connection test fails**: Check host, port, database, username, password, and SSL settings. Verify the SQL user has permission to connect and write. - **No data appears in SQL**: Confirm the mapping is correct and the target table exists or is allowed to be created/updated by your schema mode. - **Manual sync not running**: Ensure the template is Active and the Credential is eligible; trigger a manual sync from the UI. - **SSL/TLS trust errors**: Ensure TLS 1.2+ is enabled on the server, the server presents a certificate with a valid chain to a publicly trusted root CA, and the connection uses the correct host name matching the certificate CN/SAN. Private CAs and self‑signed certificates are not supported. - **Incidents and notifications**: If errors occur repeatedly, notifications are sent to recipients configured under “Report Incidents To.” Related incidents are batched to reduce noise, and cleared automatically when items recover. ### Manual sync from Credential page When a Credential has an active SQL Sync workflow, administrators will see a sync bar on the Credential page. From here you can: - Click **Sync now** to immediately attempt a synchronization - Click **Stop sync** to stop the active synchronization workflow :::::warning Stopping the sync is permanent. The Credential will no longer sync on status changes or during the daily fallback check, and the synchronization cannot be restarted. ::::: You normally do not need to use Sync now because AMR triggers automatically on status changes and also runs a daily fallback check. Use this action mainly to recover from an initial sync failure or after fixing mapping/permission issues. --- ## AMR SQL Transfer AMR SQL Transfer lets you perform a one-time transfer of Credential data directly into a Microsoft SQL Server (MSSQL) table. It mirrors the intent of File Transfer but writes to SQL instead of generating a file. Use it when a downstream system expects data to be inserted or upserted into a database once, typically when a Credential is produced. To explore other AMR methods for moving Credential data to third‑party systems, see the [Access Management Router (AMR)](/docs/integrations/amr). --- ## Prerequisites :::info - **Availability**: This feature is available for Enterprise plans. Contact your Breeze representative or dealer for options. ::: :::note[Required roles] **Required roles**: - `System Administrator` - `Data Exporter` You need these roles to configure and use AMR SQL Transfer. ::: Before you start: - Access to the **Breeze Admin Portal** - Access to a **Microsoft SQL Server** instance and credentials - Know where the data should be stored: database, optional schema, and table name - Your Domain/Tenant must have the **AMR SQL** feature enabled --- ## MSSQL requirements and permissions Have these connection details ready: - Host (DNS or IP) and Port (default `1433`) - Database name - Username and Password (password is write‑only in the UI) - TLS encryption (TLS 1.2+ required) using a publicly trusted CA certificate (private CAs and self‑signed certificates are not supported) Permissions depend on schema management availability for transfer: - `none`: INSERT/UPDATE on the target table - `create` / `create_update` (if enabled): permissions to create/alter the target table ::::note Only SQL logins are supported. Windows/AD or certificate‑based authentication methods are not supported. :::: --- ## Available data fields and mapping Use the built‑in Mapping editor to choose Breeze fields and assign their destination SQL columns. You do not enter mapping strings manually. How it works: 1. Open the Mapping editor from the template. 2. Pick a Breeze field from the dropdown list. 3. Type the SQL column name you want to write to, then click Add field. 4. Repeat for all needed fields. Optionally enable a dedicated SQL timestamp column to store the transfer time. Guidelines: - Include only the fields required by the receiving system. - SQL column names must be valid identifiers (start with a letter/underscore; contain only letters, numbers, underscores; max 128 chars). - Avoid reserved SQL keywords as column names. See also: [Mapping settings](#mapping-settings) and [Available Data Fields](/docs/integrations/amr/available-data-fields). --- ## Transfer trigger AMR SQL Transfer is a one‑time push that runs immediately after a Credential is produced. There is no manual trigger and no daily fallback. If you need ongoing updates, use SQL Synchronization instead. --- ## Create a new AMR SQL Transfer configuration 1. Go to your **Tenant** in the Breeze Admin Portal 2. Open **Templates** → **AMR Transfer Templates** 3. Click **Create New AMR Transfer Template** 4. Select the AMR Transfer Type: **SQL_PUSH** and fill in the initial SQL settings. See: [SQL connection settings](#sql-connection-settings) and [Target table](#target-table). 5. Click **Test Connection**. You must get a success message to proceed. See: [Test connection](#test-connection). 6. Click **Save**. The configuration drawer opens for further settings. 7. Add incident recipients (recommended) so you’re notified if something goes wrong. See: [Incident notifications](#incident-notifications-report-incidents-to). 8. Configure field mappings: choose Breeze fields and assign SQL columns. Optionally enable a timestamp column. See: [Available data fields and mapping](#available-data-fields-and-mapping) and [Mapping settings](#mapping-settings). 1. Set other options, then save. See: [Key configuration settings](#key-configuration-settings). 1. You can change SQL settings later if needed. See: [SQL connection settings](#sql-connection-settings). After these steps, your template is ready. Associate it with Credential Templates as needed. --- ## Configuring AMR SQL Transfer ### Key configuration settings | Setting | Description | | ----------------------- | --------------------------------------------------------- | | Name | Human‑readable name for the configuration | | Active | Only active templates can be used by Credential Templates | | Allowed for sub-tenants | Make available to sub‑tenants on the same System Domain | ### SQL connection settings Same as SQL Synchronization: | Setting | Description | Example | | -------- | ------------------------------------- | ------------------ | | SQL Type | RDBMS type | mssql | | Host | DNS or IP of the SQL Server | sql.mycorp.local | | Port | TCP port | 1433 | | Database | Database name | access_integration | | Username | SQL login user | breeze_writer | | Password | SQL login password (write‑only in UI) | •••••• | | SSL | Encrypt connection (true/false) | true | ### Target table | Setting | Description | Example | | ----------------- | ----------------- | --------------- | | Schema (optional) | Schema name | dbo | | Table | Target table name | amr_credentials | ### Mapping settings 1. Open the **Mapping** editor 2. Pick Breeze fields and assign SQL columns 3. Ensure the target table has keys/columns required by downstream systems 4. Save when validation passes ### Test connection Use **Test Connection** to verify the SQL connectivity (basic health check such as `SELECT 1`). Fix any errors before activating. --- ## Troubleshooting - **Connection test fails**: Check host, port, database, username, password, and SSL settings. Verify the SQL user has permission to connect and write. - **No data appears in SQL**: Confirm the mapping is correct and the target table exists (or that schema management allows creating/updating it, if available). - **Incidents and notifications**: If errors occur repeatedly, notifications are sent to recipients configured under “Report Incidents To.” Related incidents are batched to reduce noise, and cleared automatically when items recover. --- ## Security and networking ::::info For complete security and connectivity requirements (TLS 1.2+ with publicly trusted CA, SQL logins only, least‑privilege access, and recommended private connectivity), see: - [Connectivity and Security for AMR SQL](/docs/integrations/amr/connectivity/sql-security-networking) - Recommended for customer‑hosted SQL (Option A): [Setting up Azure App Service Hybrid Connection to Your SQL Server](/docs/integrations/amr/connectivity/azure-app-service-hybrid-connections) :::: --- ## When a transfer fails If the one‑time transfer fails: - Incident recipients (if configured) are notified by email. Related incidents are batched to avoid spam and are cleared automatically when a later attempt succeeds. - A warning appears on the Credential page with a Retry button. Use Retry after you’ve resolved the underlying issue (for example connectivity, or mapping). --- ## Incident notifications (Report incidents to) Add one or more email recipients under "Report incidents to" to be informed about failures and other important events for this AMR template. What you’ll receive: - Emails when the system detects repeated errors during push activities for this template. - Messages are batched within a short window to avoid inbox spam. - Each email groups identical errors together and shows a single sample technical detail with a tidy list of affected Credentials (with tenant‑aware links). - If a Credential later succeeds before the email is sent, it is removed from the batch. If all items recover, no email is sent. - Emails never include sensitive secrets such as passwords. Good practices: - Use a shared mailbox or distribution list for on‑call/ops teams. - Keep recipients scoped to people responsible for integrations. - Review incidents and resolve underlying mapping, connectivity, or permission issues. --- ## AMR Webhooks Coming soon. --- ## Integrations Integrations in Breeze help you connect the platform with your existing systems and workflows. This page gives you an overview of the integration features available and points you to detailed guides. ## What are Integrations? Integrations allow Breeze to work seamlessly with your other business systems, such as access control systems, HR platforms, databases, and custom applications. They enable automatic data sharing and synchronization, reducing manual work and ensuring information stays up to date across all your systems. ## Integration Features ### Access Management Router (AMR) The Access Management Router (AMR) automatically moves Credential data from Breeze to your ecosystem securely and in real time. It connects Breeze to access control systems, HR/ERP platforms, and custom applications so the right people get the right access—on time and with minimal manual work. **Key Benefits:** - **Speed**: Data flows as soon as a Credential is produced, activated, deactivated, or deleted - **Choice**: Multiple delivery methods to integrate with file-based systems, databases, or APIs - **Control**: Field-level mapping, tenant-aware incident notifications, and safe retry flows **Popular Use Cases:** - Access control onboarding: Send new employee card data to your physical access control system (PACS) the moment a card is produced - Badge lifecycle updates: Keep status in sync when a card is activated, deactivated, or deleted - Directory/HR alignment: Mirror key identity attributes (names, photos, identifiers) to downstream systems - Temporary or visitor cards: Push one-time records to a database for short-lived access :::info **AMR Availability**: AMR is available for Enterprise plans only. Contact your dealer or Breeze representative to learn more about our Enterprise plans. ::: ## Getting Started To learn more about setting up and managing integrations in Breeze, explore the following sections: - **[Access Management Router (AMR)](./amr/)** - Automatically sync Credential data with your systems - **[AMR Setup Guides](./amr/)** - Step-by-step instructions for configuring different integration methods ## Common Tasks - Set up file-based integrations for access control systems - Configure database synchronization for HR platforms - Map Credential fields to your system's requirements - Monitor integration activity and troubleshoot issues - Configure incident notifications for integration errors For detailed instructions on these tasks, see the [AMR documentation](./amr/). --- ## Introduction Welcome to the Breeze documentation! Breeze is an Identity and Access Management (IAM) platform that helps you create, manage, and distribute physical and digital Credentials—from employee ID cards to mobile Credentials. Whether you're managing Credentials for a single organization or multiple Tenants across different locations, Breeze provides the tools you need to streamline your Credential management workflow. :::note[Documentation in Progress] This documentation is continuously being updated and expanded. Some features may have more detailed guides than others, and new content is added regularly. If you can't find what you're looking for or have questions, please contact our support team. ::: ## What You Can Do with Breeze - **[Create and Manage Credentials](/docs/credential-management/)**: Design, produce, and track physical ID cards and mobile Credentials throughout their lifecycle - **[Manage Users and Access](/docs/user-administration/)**: Control who can access what, assign roles, and manage user accounts across your organization - **[Integrate with Your Systems](/docs/integrations/amr/)**: Connect Breeze to your access control systems, HR platforms, and databases through the Access Management Router (AMR) - **[Configure Authentication](/docs/authentication/)**: Set up Single Sign-On (SSO) to simplify user access - **[Customize Templates](/docs/template-management/)**: Design Credential templates that match your brand and requirements - **[Manage Production](/docs/tenant-administration/)**: Configure production sites, quality checks, and order workflows ## Documentation Sections This documentation is organized into sections covering different aspects of Breeze: - **[Credential Management](/docs/credential-management/)**: Learn how to create, manage, and track Credentials - **[Authentication](/docs/authentication/)**: Set up SSO and manage user authentication - **[Integrations](/docs/integrations/)**: Connect Breeze with your existing systems - **[Tenant Administration](/docs/tenant-administration/)**: Configure and manage Tenant settings and production sites - **[Domain Administration](/docs/domain-administration/)**: Manage Domains, products, and terms & conditions - **[User Administration](/docs/user-administration/)**: Understand roles, permissions, and user lifecycle management - **[Template Management](/docs/template-management/)**: Create and customize Credential templates - **[Troubleshooting](/docs/troubleshooting/)**: Find solutions to common issues We're here to help you get the most out of Breeze. Start by exploring the section that matches what you're trying to accomplish, or use the search function to find specific topics. Happy reading! 📖 --- ## Approval Workflows (Card Templates) Card Templates can require approvals before Credentials are issued. You can also route Duo ID approval requests to a delegated Tenant so approvals are handled in a central place. ## Who this is for This page is for administrators who configure approval behavior for Card Templates. ::::note[Required Roles] **Required roles**: `System Admin` + `Production - Create Layouts` To perform the following steps, you need to have the roles listed above. :::: ## Where to find approval settings 1. Navigate to **Templates** → **Card Templates**. 2. Open a template and click **Edit Card Template**. 3. Go to the **Approvals** tab. ## Template approvals The **Approvals** section controls whether Credentials created from this template must be approved before they can be issued. - Click **Change setting** to update the approval configuration. - When enabled, the UI shows **Enforced Approval activated**. ## Duo ID Approval Routing If your template uses Duo ID, you can delegate Duo ID approvals to a specific Tenant. This is useful when you want one Tenant (for example, “Central approvals”) to handle approvals for multiple Tenants. ### Configure the delegated Tenant 1. In the **Production elements** tab, set **Duo ID** to **Enabled**. 2. Go to **Approvals**. 3. In **Duo ID Approval Routing**, select a Tenant in **Duo ID Approval Delegated Tenant**. 4. Click **Save**. ### What happens after you enable routing - When a Duo ID request is submitted for a Credential created from this template, Breeze routes the approval request to the delegated Tenant. - Approvers review the request from the delegated Tenant’s **Duo ID requests** queue. ### Disabled behavior If Duo ID is disabled on the template, the **Duo ID Approval Routing** section still appears, but shows a **Disabled** indicator and the dropdown is hidden. ::::note[Routing timing] Routing is applied when the Duo ID request is submitted. Changing the delegated Tenant later does not move already-submitted requests. :::: ## Who can approve Duo ID requests To approve Duo ID requests in a Tenant, a user typically needs: - A base admin role (for example: `Administrator`) and - The task role `Approver` See: [Roles and Permissions](/docs/user-administration/roles) --- ## Editing Card Templates Card Templates are where you define how physical Credential cards are produced: layouts, fields, encoding, approvals, and optional Duo ID behaviors. The editor is organized into tabs so you can work on one configuration area at a time. ## Who this is for This guide is for administrators who manage Card Templates for a Tenant or production setup (for example: production site operators, template designers, and system operators). ::::note[Required Roles] **Required roles**: `System Admin` + `Production - Create Layouts` To perform the following steps, you need to have the roles listed above. :::: For an overview of roles in Breeze, see [Roles and Permissions](/docs/user-administration/roles). ## Open the editor 1. Navigate to **Templates** → **Card Templates**. 2. Find the Card Template you want to update. 3. Click **Edit Card Template**. The editor opens in a modal dialog with multiple tabs. ## Editor tabs The Card Template editor is organized into the following tabs: - **Production elements** — Status, order type, layouts, fields, and general production settings - **Encoding and ranges** — CSN readings, encoding files, number ranges, formulas, and manual encoding settings - **Approvals** — Approval workflow settings and Duo ID Approval Routing - **Information** — Modification history and template metadata - **Access control** — AMR Transfer Template connections - **Advanced** — Advanced configuration such as background removal settings ## Production elements The **Production elements** tab contains the core configuration for card production. ### Status and order type - **Status**: Toggle between **Active** and **Inactive**. - **Order type**: Choose between **Single** (individual orders) and **Batch** (bulk orders). ### AMR Sync and Duo ID - **AMR Sync**: Toggle between **Disabled** and **Activated**. - **Duo ID**: Toggle between **Disabled** and **Enabled**. When **Enabled**, you can configure **Duo ID Approval Routing** in the **Approvals** tab. ## Approvals The **Approvals** tab (also labeled Godkjenninger / Order flow in Norwegian) contains settings for approval workflows and Duo ID Approval Routing. ### Approval settings The **Approvals** section controls whether Credentials created from this template require approval. - **Enforced Approval activated**: When enabled, Credentials require approval before they can be issued. - Click **Change setting** to update the approval configuration. ### Duo ID Approval Routing When Duo ID is enabled on your template (in the **Production elements** tab), you can configure a **delegated Tenant** for Duo ID approvals. This routes new Duo ID approval requests created from this template to a specific Tenant so you can centralize approvals. **How it works:** 1. Enable **Duo ID** in the **Production elements** tab. 2. Open the **Approvals** tab. 3. In **Duo ID Approval Routing**, select a Tenant in **Duo ID Approval Delegated Tenant**. 4. Click **Save**. **What happens:** - New Duo ID approval requests created from this template are assigned to the selected delegated Tenant. - Approvers review the request from the delegated Tenant’s **Duo ID requests** queue. ::::note[Visibility behavior] The Duo ID Approval Routing section is always visible: - When Duo ID is **Enabled**, the dropdown is available. - When Duo ID is **Disabled**, the section shows a **Disabled** indicator and the dropdown is hidden. :::: ::::note[Routing timing] Routing is applied when the Duo ID request is submitted. Changing the delegated Tenant later does not move already-submitted requests. :::: ## Encoding and ranges The **Encoding and ranges** tab contains settings used during RFID encoding and numbering. This typically includes: - **CSN Readings** (high frequency / low frequency) - **CardSDK Encoding DSC File(s)** (optional) - **Number Ranges** (up to 3) - **Formulas** (up to 3) - **Manual encoding** and optional production instructions ## Information The **Information** tab shows administrative details, such as when the template was created and last updated. ## Access control The **Access control** tab is where you connect **AMR Transfer Templates** to your Card Template. These templates control what data Breeze sends to access control systems when Credentials are activated. Learn more: [AMR documentation](/docs/integrations/amr/) ## Advanced The **Advanced** tab contains advanced production settings such as background removal configuration. ## Save or discard changes - Click **Save** to apply changes. - Click **Close** to exit the editor. If you made changes and click **Close**, Breeze may prompt you to discard your unsaved changes. ## What's next? - [Card Templates overview](/docs/template-management/card-templates/) - [Mobile Credential Templates](/docs/template-management/mobile-credential-templates/) --- ## Card Templates Card Templates in Breeze help you create reusable configurations that standardize how physical Credential cards are created, printed, and encoded. This page gives you an overview of Card Template features and points you to detailed guides. ::::note[Required Roles] **Required roles**: `System Admin` + `Production - Create Layouts` To create or edit Card Templates, you need to have the roles listed above. :::: ## What are Card Templates? Card Templates are reusable configurations that define how physical Credential cards are produced. Instead of configuring settings for each card individually, you can create a template once with all your preferred settings—including card layouts, encoding settings, approval workflows, and production configurations—then apply it to multiple Credentials. **Key Benefits:** - **Consistency**: Ensure all cards follow the same design and configuration standards - **Efficiency**: Set up complex settings once and reuse them across multiple cards - **Time Savings**: Reduce manual configuration work when creating new Credentials - **Standardization**: Maintain consistent settings across departments, locations, or use cases ## Key Features Card Templates include configuration for: - **Production Elements**: Card layouts (front and back), carrier selection, field settings, and general production settings - **Encoding and Ranges**: RFID encoding configuration and number range assignments - **Approvals**: Approval workflow settings and Duo ID approval routing - **Information**: Template metadata, descriptions, and instructions - **Access Control**: Access right configurations for card-based access control - **Advanced**: Additional advanced configuration options ## Getting Started To learn more about creating and managing Card Templates in Breeze, explore the following sections: - **[Editing Card Templates](./editing-templates)** — Edit templates and configure all settings - **[Approval Workflows](./approval-workflows)** — Configure approval settings and Duo ID approval routing ## Common Tasks - Create templates to standardize card production - Configure card layouts and visual design - Set up approval workflows and Duo ID approval routing - Configure encoding settings and number ranges - Manage multiple templates for different use cases or departments - Edit existing templates to update settings For detailed instructions on these tasks, see the [Editing Card Templates documentation](./editing-templates). --- ## Template Management Template Management in Breeze helps you create reusable configurations that standardize how Credentials are created and managed. This page gives you an overview of template management features and points you to detailed guides. ## What are Templates? Templates are reusable configurations that define how Credentials are created, provisioned, and synchronized. Instead of configuring settings for each Credential individually, you can create a template once with all your preferred settings, then apply it to multiple Credentials. **Key Benefits:** - **Consistency**: Ensure all Credentials follow the same configuration and standards - **Efficiency**: Set up complex settings once and reuse them across multiple Credentials - **Time Savings**: Reduce manual configuration work when creating new Credentials - **Standardization**: Maintain consistent settings across departments, locations, or use cases ## Template Types ### Mobile Credential Templates Mobile Credential Templates define how mobile ID Credentials are provisioned and synchronized with your mobile ID provider. They bundle provider settings, sync behavior, notification preferences, and other configurations into a single reusable template. **Key Features:** - Provider connection settings for mobile ID services - Automatic synchronization with mobile ID providers - Number range configuration for Credential identifiers - Incident notification settings - Optional card layout templates for previews - Duo ID approval routing configuration ### Card Templates Card Templates define how physical Credential cards are produced, including card layouts, encoding settings, approval workflows, and production configurations. **Key Features:** - Card layout configuration (front and back pages) - RFID encoding settings - Approval workflow configuration - Duo ID approval routing - Number range assignments - Access control settings ## Getting Started To learn more about creating and managing Templates in Breeze, explore the following sections: - **[Mobile Credential Templates](./mobile-credential-templates/)** - Create and manage templates for mobile ID Credentials - [Template List](./mobile-credential-templates/template-list) - View and manage templates - [Creating Templates](./mobile-credential-templates/creating-templates) - Create new templates - [Editing Templates](./mobile-credential-templates/editing-templates) - Edit templates and configure settings - [Deleting Templates](./mobile-credential-templates/deleting-templates) - Remove templates - [Provider Synchronization](./mobile-credential-templates/provider-synchronization) - Understand automatic synchronization - **[Card Templates](./card-templates/)** - Create and manage templates for physical credential cards - [Editing Templates](./card-templates/editing-templates) - Edit templates and configure all settings ## Common Tasks - Create templates to standardize Credential creation - Configure provider settings and synchronization schedules - Set up notification preferences for template-related incidents - Configure Duo ID approval routing to centralize approval workflows - Manage multiple templates for different use cases or departments - Edit existing templates to update settings For detailed instructions on these tasks, see the [Mobile Credential Templates documentation](./mobile-credential-templates/) and [Card Templates documentation](./card-templates/). --- ## Creating a New Template You'll create a new template when you need a different configuration for mobile IDs. Maybe you're setting up templates for different departments, or you need separate templates for testing and production. Each template lets you define its own provider settings, sync schedule, and visibility rules. :::note[Required Roles] **Required roles**: `System Administrator`, `Manage Templates - Mobile Credential` To create new templates, you need one of the roles listed above. ::: ## Start creating 1. Go to **Templates** → **Mobile Credential** 2. Click the **"Create New Mobile Credential Template"** button at the top of the template list ![Create New Template Dialog](./_images/mobile-credential-templates-create-dialog.png) ## Fill in the basics When the create dialog opens, you'll need to provide a few details: - **Provider**: Select provider (Currently only "STid Mobile ID Provider" is supported) - **Name**: Give your template a clear, descriptive name (this is required). Something like "Corporate Headquarters" or "Remote Workers" works better than "Template 1" - **Description**: This is optional, but adding a quick note about the template's purpose helps later—especially if you're managing multiple templates The name is what you'll see in the template list and when selecting templates, so make it something you'll recognize. ## Create and configure Click **"Create"** to create the template. The [template editor](./editing-templates) will open automatically so you can configure provider settings, sync behavior, and other options. Don't worry about getting everything perfect right away—you can always come back and edit the template later if you need to adjust settings. ## What's next? Once your template is created, you'll want to: - **[Edit template settings](./editing-templates)** — Review all the configuration options available --- ## Deleting Templates :::warning[Permanent Action] Deleting a template is a permanent action that cannot be undone. Ensure you have backups of any important configuration data before proceeding. ::: ## Step 1: Initiate Deletion 1. In the template list, click the **"Slett"** (Delete) button next to the template you want to remove 2. A confirmation dialog will appear ![Delete Confirmation Dialog](./_images/mobile-credential-templates-delete-confirmation.png) ## Step 2: Confirm Deletion The deletion process includes a safety confirmation to prevent accidental deletions: 1. **Review the Warning**: The dialog shows the template name and warns that the action cannot be undone 2. **Type Confirmation**: Enter the exact template name in the "Bekreft navn for å slette" (Confirm name to delete) field 3. **Delete**: The "Slett" button will become enabled once you've typed the correct name 4. **Cancel**: Click "Avbryt" (Cancel) to abort the deletion :::note[Safety Feature] The name confirmation requirement prevents accidental deletions and ensures you're deleting the intended template. ::: ## Considerations Before Deleting Before deleting a template, consider: - Are there active Credentials using this template? - Do you have a backup of the template configuration? - Is the template used in any automated workflows? ## Related Topics - **[Creating Templates](./creating-templates)** - Create new templates - **[Editing Templates](./editing-templates)** - Modify existing templates instead of deleting --- ## Editing Templates You'll spend most of your time editing templates—whether you're adjusting provider settings, changing sync schedules, or updating field configurations. The template editor organizes everything into clear sections, making it easy to find what you need. ## Opening the editor You can open the template editor in two ways: 1. Click the **"Edit"** button next to any template in the list 2. Double-click any template row Either way, you'll see the same editor with all the configuration options. ![Template Editor Detail View](./_images/mobile-credential-templates-editor-detail.png) ## Editor overview The template editor is organized into distinct sections. Each section has its own **Edit** button or inline controls, so you can focus on one thing at a time. You don't need to configure everything at once—just work through the sections you need. ## Template name and provider connection At the top of the editor, you'll find: **Template Name** — Edit this directly in the text field. Use descriptive names like "Employee Mobile ID" or "Visitor Access" so they're easy to identify later. **Provider Connection** — The **"Check Connection & Credits"** button lets you test your provider connection. Use this after configuring Credentials to verify everything works and check your available credits. The status will show whether the connection has been tested yet. ## Settings The Settings section contains quick toggles for common options. Each setting has two options you can switch between: | Setting | Option | What it does | | --------------------- | ------------- | --------------------------------------------------------------------------------- | | **Visible in portal** | **Visible** | Operators can see and use this template when ordering or creating new Credentials | | | **Hidden** | Template stays hidden from operators (useful for unfinished or testing templates) | | **AMR Sync** | **Sync** | AMR (Access Management Request) synchronization is enabled | | | **Disabled** | AMR sync is turned off | | **Provision Method** | **Automatic** | Credentials are provisioned immediately when issued | | | **Manual** | Requires manual provisioning steps | | **Duo ID** | **Enabled** | Template supports Duo ID functionality | | | **Disabled** | Standard mobile ID Credentials only | :::note[Visibility Requirements] Templates can't be made visible until provider configuration is complete. Incomplete configurations automatically stay hidden to prevent errors during Credential issuance. ::: ## General settings Click **"General settings"** to expand this section. Here you'll find: | Field | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Private ID Field** | Maps your internal Credential data to the provider's synchronization fields. Defaults to "Credential - Number", but you can select a different field if needed. | | **Send end date** | Check this box if you want Credential expiration dates sent to the provider. | | **External layout name** | Optional. Use this if you want to configure and design the layout in the STid portal instead of using Breeze layouts. Generally not recommended—only use in specific cases where external layout configuration is required. See [Layout](#layout) section for the recommended approach. | | **External Reference** | Optional custom identifier for linking to external systems like CRM or HR platforms. | | **Description** | Add detailed notes about the template's configuration. This helps administrators and operators understand how to use it. | | **Instructions** | Step-by-step guidance for operators who will issue Credentials using this template. This appears as user-facing help text. | ## Account Credentials :::note[Required Roles] **Required roles**: `System Administrator`, `Manage Templates - Mobile Credential` To configure provider settings, you need one of the roles listed above. ::: Click **"Edit"** to configure your provider connection. This opens a dialog where you enter: | Field | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Provider username** | Your authentication Credential for provider API access. This is stored securely. | | **Provider password** | Your provider account password. | | **Site ID** | Identifies your organization's site within the provider system. You'll get this from your mobile ID provider. | | **Provider configuration ID** | A specific configuration identifier for your provider setup. Also provided by your mobile ID provider. | After entering Credentials, click **"Validate"** to test the connection before saving. The dialog shows a step-by-step progress indicator as you configure each part. :::info[Connection Testing] Always test provider connections after configuration changes using the "Validate" button in the Credentials dialog, or the "Check Connection & Credits" button at the top of the editor. ::: ## Sync Configuration Click **"Edit"** to configure provider synchronization settings. This opens a dialog where you can: **Enable/Disable Sync** — Turn automatic synchronization on or off. When enabled, Breeze automatically keeps mobile IDs synchronized between Breeze and your mobile ID provider. The dialog shows your current sync status and lets you toggle synchronization for this template. For more information about how provider synchronization works, see **[Provider Synchronization](./provider-synchronization)**. ## Incident Recipients Click **"Edit"** to configure who receives alerts when something goes wrong. Enter email addresses separated by semicolons, like `security-ops@company.com;helpdesk@company.com`. Having multiple recipients ensures someone gets notified even if one email address has issues. **What triggers incidents:** - Connection failures — Provider connectivity issues - Sync errors — Synchronization process failures - Provisioning issues — Problems creating Credentials - Authentication errors — Provider Credential validation failures ## Layout Click **"Edit"** to select a card layout for this template. The layout you choose serves multiple purposes: - **Credential Preview** — Used as a template when creating the Credential Preview in Breeze - **Provider Transfer** — The image is transferred to your mobile ID provider (STid) - **Mobile ID App** — This will be the card design shown in the Mobile ID app This is the default behavior and is the recommended approach for most use cases. ### Alternative: External Layout Configuration If you want to configure and design the layout in the STid portal instead of using Breeze layouts, you can enter the layout name in the **External layout name** field under **General settings**. This approach is generally not recommended and should only be used in certain specific cases where external layout configuration is required. ## Template Field Settings This section shows all the fields used when issuing Credentials from this template. ### Default fields Templates include some predefined fields: | Field | Type | Requirement | Description | | ----------------------- | ---- | ----------- | ----------------------------------------------- | | **Person - Email** | TXT | Required | Primary contact email for the Credential holder | | **Person - First Name** | TXT | Required | First name of the Credential holder | | **Person - Last Name** | TXT | Required | Last name of the Credential holder | Each field shows its type (like TXT) and whether it's required. Each field has three edit buttons: - Configure field properties - Set validation rules - Control display settings ### Adding custom fields Click **"Add field"** to add a new field. Configure: | Setting | Description | | --------------- | ------------------------------------------- | | **Field Name** | Give it a clear, descriptive name | | **Field Type** | Choose the data type (TXT, NUM, DATE, etc.) | | **Requirement** | Mark it as required or optional | ## Background Removal Settings Click **"Change setting"** to configure how photo backgrounds are handled. **Background Color** — Controls what happens when photo backgrounds are removed. Default is white (#FFFFFF). | Option | Description | | --------------- | ------------------------------------ | | **Transparent** | Keeps the alpha channel (PNG format) | | **Solid Color** | Flattens to the specified hex color | ## Duplicate vCard Handling Click **"Change setting"** to configure what happens when the same vCard already exists: | Option | Description | | ----------- | --------------------------------------------------------------------------------------------------- | | **ERROR** | The workflow fails if a duplicate exists. Gives you strict control but may cause workflow failures. | | **REPLACE** | The existing vCard is replaced with new data. **This is the default behavior for new templates.** | | **REUSE** | The existing vCard is reused instead of creating a new one | :::note[Default Behavior] When you create a new Mobile Credential Template, **REPLACE** is the default conflict resolution strategy. This means if a vCard with the same email already exists, it will be replaced rather than causing an error. You can change this setting at any time by clicking **"Change setting"** and selecting a different option. ::: :::warning[Duplicate Handling] Choose carefully. ERROR mode gives you control but may cause failures. REPLACE and REUSE handle duplicates automatically but could have unintended consequences. ::: ## External Data Sources Click **"Edit"** to configure external data source lookup for this template. External data sources allow operators to automatically retrieve person data from external systems (such as Norwegian Folkeregisteret) during Credential ordering. **How it works:** 1. **Connect data source** — Select an external data source that has been configured in Domain Administration 2. **Configure field mappings** — Map fields from the external data source response to Credential template fields 3. **Enable lookup** — Operators can then enter a search identifier (e.g., 11-digit Norwegian personal identity number) during Credential ordering 4. **Automatic population** — System retrieves person data and populates Credential fields automatically :::note[Prerequisites] Before you can connect an external data source to a template, the external data source must be created and configured in **Domain Administration** → **External data sources**. See [External Data Sources](/docs/domain-administration/external-data-sources) for configuration instructions. ::: :::info[Authentication Requirements] Some external data sources (like Norwegian Folkeregisteret) require Level 4 authentication (BankID) for natural person lookups. Operators will be prompted to authenticate when performing lookups. ::: For more information about external data sources, see [External Data Sources](/docs/domain-administration/external-data-sources). ## Duo ID Approval Routing When Duo ID is enabled on your template, you can configure a delegated Tenant for Duo ID approvals. This allows you to route all Duo ID approval requests created from this template to a specific Tenant, helping you centralize approvals in fewer Tenants. **How it works:** 1. **Enable Duo ID** — Set Duo ID to **"Enabled"** in the Settings section (the Duo ID Approval Routing section is only visible when Duo ID is enabled) 2. **Select delegated Tenant** — Choose a Tenant from the **"Duo ID Approval Delegated Tenant"** dropdown 3. **Save the template** — The setting persists and applies to all new Duo ID requests created from this template **What happens:** - When a Credential is created from this template and a Duo ID request is submitted, the request routes to the delegated Tenant instead of the Credential's owning Tenant - Approvers with Admin + Approver access on the delegated Tenant can view and approve these requests - The delegated Tenant's Duo ID approval queue and pending counters reflect these requests :::note[Visibility] The Duo ID Approval Routing section is only visible when Duo ID is enabled on the template. If Duo ID is disabled, this section is hidden. ::: :::info[Clearing the Setting] To remove the delegated Tenant and revert to default routing behavior, clear the Tenant selection and save the template. Duo ID approvals will then route to the template's default Tenant (existing behavior). ::: :::note[Routing Timing] Routing is applied when the Duo ID request is submitted. Changing the template's delegated Tenant later does not move already-submitted requests. ::: ## Number Ranges and Formulas Click **"Edit"** to assign number ranges and formulas: **Number Series Assignment** — Assign number ranges for Credential identifier generation. You can link to existing number series or create new ones. Templates can use up to 3 number series per Credential. **Formula Assignment** — Apply calculation formulas for dynamic field values. Useful for automatic date calculations, conditional values, and formatting rules. ## Saving your changes 1. Make your configuration changes in any section 2. Click **"Save"** at the top right to save your changes 3. Click **"Close"** to return to the template list without saving Remember, you can always come back and edit things later—you don't need to get everything perfect in one session. ## Before making a template visible Before operators can use your template, make sure: - Provider Credentials are valid and tested (use "Check Connection & Credits") - Required fields are properly configured - Sync settings match your needs - Incident recipients are set up correctly ## What's next? You've configured your template! After saving, operators can start using it to issue mobile ID Credentials. --- ## Mobile Credential Templates ## Overview Mobile Credential Templates are reusable configurations that define how mobile ID Credentials are provisioned and synchronized. A template bundles provider settings, sync behavior, notification preferences, and other settings into a single configuration that you can apply to multiple Credentials. When you issue a Credential from a template, it automatically follows all the rules and settings defined in that template. This means you can set up your mobile ID provider connection, sync schedule, and other settings once, then reuse them for every Credential issued from that template. ## What a template contains A Mobile Credential Template includes: - **Provider settings** — Connection details for your mobile ID provider (such as STid Mobile ID) - **Sync configuration** — How and when Credentials synchronize with the provider - **Number ranges** — Rules for generating Credential identifiers - **Notification settings** — Who receives alerts when issues occur - **Card layouts** — Optional visual templates for Credential previews ## Who can create templates :::note[Required Roles] **Required roles**: `System Administrator`, `Manage Templates - Mobile Credential` To create or manage Mobile Credential Templates, you need one of the roles listed above. ::: ## How it works When you create a Credential using a template, Breeze automatically applies all the template's settings. The template also handles synchronization with your mobile ID provider, keeping Credential status and data up to date automatically. You can create multiple templates for different use cases—for example, separate templates for different departments or locations, each with its own provider settings and sync schedule. ## Where to find it Navigate to **Templates** → **Mobile Credential**. ## Learn more - **[Template List](./template-list)** — View and manage templates - **[Creating Templates](./creating-templates)** — Create new templates - **[Editing Templates](./editing-templates)** — Edit templates and configure all settings - **[Deleting Templates](./deleting-templates)** — Remove templates - **[Provider Synchronization](./provider-synchronization)** — Understand how automatic synchronization works - **[External Data Sources](/docs/domain-administration/external-data-sources)** — Configure external data sources for automatic person data lookup --- ## Provider Synchronization Have you ever wondered what happens when someone's mobile ID gets deactivated in your provider's system, or when status changes happen outside of Breeze? Provider synchronization handles all of that for you—automatically keeping everything in sync between Breeze and your mobile ID provider (like STid) so you don't have to worry about it. Think of it as having a helpful assistant that periodically checks both systems and makes sure they match. When enabled, Breeze quietly runs these checks on a schedule you set, updating statuses, catching changes, and making sure nothing falls through the cracks. ## Why this matters Imagine this scenario: An employee's mobile ID gets revoked in the STid portal, but Breeze still shows it as active. Without synchronization, operators might try to use or issue Credentials based on outdated information. With provider synchronization enabled, Breeze automatically catches that change and updates the status. Here's what you get when it's enabled: - **Always accurate statuses** — If someone's mobile ID gets activated, deactivated, or changed in your provider system, Breeze knows about it automatically - **No manual catch-up** — You don't have to remember to check or manually sync when things change elsewhere - **Peace of mind** — Both systems stay in sync without you having to think about it - **Better visibility** — You can see exactly when the last sync happened, so you know your data is fresh ## How it works behind the scenes When you enable provider synchronization for a template, here's what happens: 1. **Breeze checks on schedule** — Based on your sync schedule (you can set how often—daily, hourly, whatever makes sense for your needs), Breeze reaches out to your provider 2. **It compares both systems** — Breeze looks at what's in your provider system versus what it has in its own database 3. **It updates automatically** — Any differences? Breeze syncs them automatically. Status changed? Updated. Something deleted? Noted. 4. **You can see when it last ran** — The template list shows you when each template last synchronized successfully, so you always know your data is current You set it once, and it just works. No need to monitor it constantly or remember to run manual syncs. ## When to turn it on You'll want to enable provider synchronization if: - **You need accurate, up-to-date information** — When operators or automated workflows rely on mobile ID statuses, you can't afford stale data - **Things change frequently outside Breeze** — If your provider system is updated by other tools, integrations, or processes, synchronization keeps Breeze in the loop - **You want to set it and forget it** — Once configured, it runs automatically without requiring attention On the other hand, you might skip it if you're just testing templates, or if you prefer to handle synchronization manually when you know changes have occurred. It's totally optional—enable it when it makes sense for your workflow. ## Setting it up Configuring provider synchronization is straightforward: 1. Open any template in the editor 2. Find the **Sync Configuration** section 3. Click **"Edit"** to open the sync settings 4. Toggle sync on or off 5. Set your sync schedule if you want to control how often it runs That's it. Once enabled, Breeze handles the rest. For step-by-step instructions, see **[Editing Templates](./editing-templates#sync-configuration)**. ## Keeping an eye on it You don't need to babysit synchronization, but it's nice to know how things are going: - **Check the template list** — The sync status column shows you at a glance which templates have sync enabled - **See when it last ran** — The "Last Synced" column tells you exactly when each template last synchronized (or shows "Never" if it hasn't synced yet) - **Review sync logs** — If something seems off, check the logs to see what happened during sync operations Most of the time, you won't need to think about it—it just runs quietly in the background keeping everything aligned. ## Related topics - **[Editing Templates](./editing-templates)** — Configure sync settings for individual templates - **[Template List](./template-list)** — View sync status across all templates --- ## Template List When you open the Mobile Credential Templates page, you'll see a list of all your templates. This is your starting point for managing how mobile IDs are set up in your organization. ![Mobile Credential Templates List View](./_images/mobile-credential-templates-list-view2.png) ## What you'll see Each template in the list shows: - **Template Number** — A unique ID that helps you identify templates at a glance - **Name** — The name you gave the template (hopefully something descriptive!) - **Provider** — Which mobile ID provider it uses (currently STid Mobile ID) - **Sync Status** — Whether automatic synchronization is turned on or off - **Last Synced** — When it last synchronized with the provider (shows "Never" if it hasn't synced yet) - **Actions** — Quick access to edit or delete buttons ## Working with templates Most of what you'll do starts from this list: - **[Create new templates](./creating-templates)** — Set up a new template when you need a different configuration - **[Edit existing templates](./editing-templates)** — Make changes to settings, provider credentials, or sync behavior - **[Delete templates](./deleting-templates)** — Remove templates you no longer need (be careful—this can't be undone) ## Finding what you need As your list of templates grows, you'll appreciate the filtering options. Say you know the template number you're looking for, or you remember it had "Production" in the name—filters help you find it quickly without scrolling. ### Filter by template number If you know the exact template number, enter it here for a precise match. Useful when you're working with a specific template and already have its number. ### Filter by name Type part of the template name to find matches. This is helpful when you remember the template's purpose (like "Corporate" or "Remote Workers") but not the exact name. **Quick tip:** Combine both filters to narrow down results even further. And if you've applied filters but want to see everything again, just clear them. ## What's next? - **[Creating Templates](./creating-templates)** — Learn how to create your first template - **[Editing Templates](./editing-templates)** — See what you can configure in the template editor --- ## Tenant Administration Tenant Administration in Breeze helps you configure and manage separate instances of the platform, each with its own settings, users, and workflows. This page gives you an overview of tenant administration features and points you to detailed guides. ## What is a Tenant? A Tenant, also known as a Portal, is a separate instance of the Breeze platform that can be used to manage Credentials, Users, and other settings. Tenants allow you to organize and separate different aspects of your organization, such as: - **Different brands**: Manage separate portals for different brand identities - **Departments**: Create dedicated portals for different departments or divisions - **Customers**: Provide isolated portals for different customer organizations Each Tenant operates independently with its own users, Credentials, templates, and configuration settings. ## Tenant Administration Features ### Production Sites A production site is a Tenant assigned to handle the production of Credentials that need to be printed or encoded. The production site is responsible for the physical production of Credentials, such as printing, encoding, and personalization. **Key Features:** - Dedicated Production module for managing Credential production - Quality check workflows to ensure Credential quality - Order lock settings for new Tenants to prevent processing issues - Domain-level or local production site configuration ### Tenant Settings Tenant settings allow you to configure how each Tenant operates, including checkout processes, order management, and production workflows. **Documented Settings:** - **Order Lock**: Prevent Tenants from placing orders until setup is complete - **Checkout Flows**: Configure different checkout processes (Default, On-the-Fly, Scheduled, Merge) - **Production Settings**: Control production workflows and quality check steps ## Getting Started To learn more about setting up and managing Tenants in Breeze, explore the following sections: - **[Production Site](./production-site.md)** - Configure and manage production sites - **[Tenant Settings](./tenant-settings/)** - Configure Tenant-specific settings and workflows - [Order Lock](./tenant-settings/order-lock.md) - Control when Tenants can place orders - [Checkout Flows](./tenant-settings/checkout-flows.md) - Configure different checkout processes ## Common Tasks - Set up a production site for Credential production - Configure quality check workflows - Enable or disable order locks for Tenants - Set up checkout flows to match your operational needs - Manage Tenant-specific settings and configurations For detailed instructions on these tasks, see the documentation sections linked above. --- ## Production Site # Production Site A production site is a Tenant assigned to handle the production of Credentials that need to be printed or encoded. The production site is responsible for the physical production of the Credentials, such as printing, encoding, and personalization. A "Production" module is available in the Breeze Portal for the production site to manage the production of Credentials. This can be accessed from the menu. Aside from the production module, the production site Tenant can be used like any other Tenant. The production site is either assigned at the Domain level (most common) or through setting up local production. If set up at the Domain level, all ordered Credentials within the Domain will be produced at the assigned production site. ## Production History (Production module) Production operators can open **Production History** to review previously produced Credentials for a Tenant. This is useful when you need to look up earlier production events and take follow-up actions like re-production or carrier-only printing. ::::note[Required roles] **Required roles**: `Production Operator` (task role) To use Production History, you need to have the role listed above for the selected Tenant. :::: ### Where to find it 1. Go to **Production**. 2. Select **Production History** (top right). ### Filter and sort history entries Production History supports sorting and filtering to help you narrow down results: - **Production date**: filter by a date range. - **Credential number**: requires an exact match. - **Tenant**: filter by Tenant name. ### Select Credentials and run follow-up actions From Production History, you can select one or more entries and start follow-up actions: - **Reproduce Credentials**: re-produce the selected Credentials using the standard re-production flow. - **Print Carrier Only**: prints carriers for selected Credentials that have carriers (Credentials without carriers are skipped). ## Production Site Settings There are several options to configure the production site to meet your needs. ### Quality Check Step After Production :::note[Required Roles] **Required roles**: `System Administrator` To perform the following steps, you need to have the roles listed above. ::: When enabled, a quality check step will be added after the production of the Credential. This step will require a user with the `Quality Inspector` role to review the Credential before it is marked as `Produced`. This is the default behavior for all Production Sites but can be disabled if not needed, which is common for small production sites. To enable or disable the quality check step after production, follow these steps: 1. Navigate to the Tenant settings page. 2. Find and expand the `Production Settings` section. 3. Click on the `Edit Production Settings` button. 4. If the Tenant is a Production Site and you have the required roles, you will see the `Production Site Settings` section. Click on the `Change Settings` button. 5. Toggle the `Quality Check Step After Production` checkbox to enable or disable the quality check step. 6. Click the `Save` button to save your changes. Here is a flowchart illustrating the flow when the Quality Check step is enabled or disabled: ### Order Lock for New Tenants :::note[Required Roles] **Required roles**: `System Administrator` To perform the following steps, you need to have the roles listed above. ::: When enabled, **new** Tenants created belonging to the Production Site will have the order lock enabled by default. This means that the Tenant will not be able to place orders until the order lock is disabled. This is typically used as a QA step to prevent orders from being placed until any issues with the Tenant or Card Template setup that could lead to processing problems are resolved. To enable or disable the order lock for **new** Tenants, follow these steps: 1. Navigate to the Tenant settings page. 2. Find and expand the `Production Settings` section. 3. Click on the `Edit Production Settings` button. 4. If the Tenant is a Production Site and you have the required roles, you will see the `Production Site Settings` section. Click on the `Change Settings` button. 5. Toggle the `Enable Order Lock for New Tenants` checkbox to enable or disable the order lock for new Tenants. 6. Click the `Save` button to save your changes. To disable (or enable) the order lock on a Tenant, a `System Administrator` must navigate to the [Tenant settings and disable the order lock](/docs/tenant-administration/tenant-settings/order-lock.md#enabledisable-order-lock). --- ## Tenant Checkout Flows # Checkout Flows ## Overview Breeze offers configurable checkout flows that allow each Tenant to use a different checkout process beyond the default cart checkout. This feature includes four checkout flows: 1. **Default Checkout** 2. **On-the-Fly Checkout** 3. **Scheduled Checkout** 4. **Merge Checkout** These different flows provide greater flexibility in how Tenants manage the ordering and production of Credentials, tailoring the process to their specific operational needs. ## What Are Checkout Flows? Checkout flows define how orders are processed from the point of adding items to the cart through to production. The four available flows---Default, On-the-Fly, Scheduled, and Merge---offer flexibility to suit various use cases, from manual checkout to fully automated processes. ## Intentions of the Feature - **Customization**: Allows Tenants to choose a checkout flow that best suits their workflow and production requirements. - **Efficiency**: Streamlines the ordering process by reducing unnecessary steps for certain use cases. - **Automation**: Enables automatic processing of orders without manual intervention, beneficial for API integrations and bulk processing. - **Control**: Offers options to merge orders and control the frequency and manner in which orders are processed by the production site. - **Cost Savings**: By merging orders, Tenants can reduce processing costs and optimize shipping. ## Configuring Checkout Flows ### Required Roles :::note[Required Roles] **Required roles**: `System Administrator` To perform the following configurations, you need to have the roles listed above. ::: ### Accessing Checkout Flow Settings 1. Navigate to the **Tenant Settings** page. 2. Open the **Production settings** tab. 3. Click on the **Edit Production Settings** button. 4. Locate the **Production Flow Settings** settings box, and hit the **Change Settings** button. ### Selecting a Checkout Flow In the **Checkout Flow** tab, you will see the available checkout flow options: - **DEFAULT** - **ON_THE_FLY** - **SCHEDULED** - **MERGE** Select the desired checkout flow for your Tenant. --- ## Checkout Flow Options ### 1. Default Checkout This is the standard checkout process where users add items to their cart and manually proceed through the checkout steps. - **Behavior**: Credentials and products are added to the cart. Users must manually check out to place an order. - **Use Case**: Suitable for most Tenants where manual review and confirmation of orders are required. ### 2. On-the-Fly Checkout #### Description The On-the-Fly Checkout flow bypasses the cart and manual checkout process. Users create Credentials that are automatically processed and added to the production queue. #### Behavior - **Menu Changes**: The "Order New Credentials" option is replaced with "Create New Credentials". - **Automatic Processing**: New Credentials are immediately processed and sent to production upon creation. - **No Cart**: There is no cart or order associated with the Credential. - **Approval Steps**: If an approval workflow is configured, Credentials still require approval before production. #### Configuration Steps 1. Select the **ON_THE_FLY** option in the Checkout Flow settings. 2. **Define Role Exceptions** (Optional): - You can specify certain user roles that will still use the Default Checkout flow. - This is useful if, for example, administrators should bypass the cart while regular users should not. #### Use Case Ideal for Tenants with local production facilities who want to produce Credentials immediately without the extra steps of cart checkout and order processing. #### Important Notes - The "Order Products and Accessories" option remains available and uses the Default Checkout flow. - Ensure users are trained on the new process, as it changes how they interact with the system. --- ### 3. Scheduled Checkout #### Description The Scheduled Checkout flow automatically checks out open carts at defined intervals. #### Behavior - **Automatic Checkout**: Items in users' carts are automatically checked out based on a schedule. - **Cron Expression**: A cron expression defines the checkout schedule. - **Default Address and Shipping Method**: Configurable defaults are used unless specified by the user. #### Configuration Steps 1. Select the **SCHEDULED** option in the Checkout Flow settings. 2. **Set Up Cron Schedule**: - Enter a cron expression to define when carts are automatically checked out. - Example: `0 0 * * *` for daily at midnight. - [Crontab.guru](https://crontab.guru/) is a useful tool for generating cron expressions. 3. **Configure Default Settings**: - **Default Address**: Specify the default shipping address for orders. - **Shipping Method**: Select the default shipping method to be used. 4. **Save** the settings. #### Use Case Beneficial for API users who place orders externally. Orders accumulate in the cart and are automatically processed without manual intervention. #### Important Notes - The scheduled flow applies to **all carts** on the Tenant. - Users can still manually check out orders through the Breeze interface. - After checkout, the order will be processed according to the Tenant's production settings like any other order. --- ### 4. Merge Checkout #### Description The Merge Checkout flow queues checked-out orders and merges them according to specified settings at scheduled intervals. #### Behavior - **Order Queue**: Checked-out orders receive the status "In Queue". - **Scheduled Merging**: Orders in the queue are merged based on the merge settings when the schedule triggers. - **Reduced Processing**: Merging reduces the number of orders processed by the production site. #### Configuration Steps 1. Select the **MERGE** option in the Checkout Flow settings. 2. **Set Up Cron Schedule**: - Enter a cron expression to define when orders are merged. - Example: `0 */6 * * *` for every six hours. - [Crontab.guru](https://crontab.guru/) is a useful tool for generating cron expressions. 3. **Configure Merge Settings**: - **Merge Type**: Choose one of the following options: - **Static**: Merge all orders using a predefined user, address, and delivery method. - **Merge All**: Merge all orders into one, using settings from the first order found. - **Merge by User**: Merge orders per user, using settings from each user's first order. - **Merge by Delivery**: Merge orders with the same delivery address and method. 4. **Define Static Settings** (if applicable): - If using the **Static** merge type, specify the user, address, and delivery method to be used for the merged order. 5. **Save** the settings. #### Use Case Useful for Tenants that want to control order frequency and reduce processing overhead by consolidating orders. #### Merge Settings Explained - **Static**: - **Purpose**: All queued orders are merged into a single order with predefined settings. - **When to Use**: When all orders should be delivered to the same location regardless of the original order details. - **Merge All**: - **Purpose**: Merges all queued orders using settings from the first order in the queue. - **When to Use**: When orders can be combined and the first order's settings are acceptable for all. - **Merge by User**: - **Purpose**: Merges orders for each user separately. - **When to Use**: When you want to consolidate orders per user. - **Note**: Each user's first order address and method are used for the merged order. - **Merge by Delivery**: - **Purpose**: Merges orders that share the same delivery address and method. - **When to Use**: When orders to the same destination can be combined to optimize shipping. #### Important Notes - Orders with different delivery settings may not be merged, depending on the merge type selected. - Ensure that merging orders does not violate any business rules or customer agreements. - Users will be informed in the checkout process that their order may be merged. --- ## Tenant Settings Tenant Settings allow you to configure how each Tenant operates, including checkout processes, order management, and production workflows. ## Documented Settings - **[Order Lock](./order-lock.md)** - Control when Tenants can place orders - **[Checkout Flows](./checkout-flows.md)** - Configure different checkout processes --- ## Tenant Order Lock # Tenant Order Lock Tenants may be blocked from placing orders by enabling the Order Lock. This is typically used as a QA step to prevent issues with the Tenant or Card Template setup that could lead to problems with processing orders. It may also be set up to be enabled by default for new Tenants created based on the [Production Site settings](/docs/tenant-administration/production-site.md#order-lock-for-new-tenants). If enabled and a user tries to place an order, the following message will be displayed (translated to the user's language): ```plaintext The checkout process is currently locked, and you are unable to proceed with the checkout at this time. This is typically due to incomplete setup of your Tenant or Credential Templates, which could lead to issues with processing your order. Please contact your system administrator to review and complete the necessary configurations. Once the lock is removed, you will be able to finalize your order. Thank you for your understanding. ``` ## Enable/Disable Order Lock :::note[Required Roles] **Required roles**: `System Administrator` To perform the following steps, you need to have the roles listed above. ::: 1. Navigate to the Tenant settings page. 2. Open the `Tenant Settings` tab and click on the `Edit Tenant Information` button. 3. If you are a `System Administrator`, you will see the `Tenant Order Lock` button below the `Tenant Name`. Click it. 4. Toggle the `Tenant Order Lock` switch to enable or disable the Order Lock. 5. Click the `Save` button to save your changes. If you enable the Order Lock, the Tenant will not be able to place orders until the Order Lock is disabled. --- ## Checkout Process Currently Locked # Checkout Process Currently Locked If you are receiving the error message "**Checkout Process Currently Locked**" when trying to check out, it means that the checkout process is currently locked. This can happen for a few reasons: - The Tenant has not yet been approved by a `System Administrator`. - The Tenant has been locked by the system due to an issue with the Tenant or Credential Templates. To resolve this issue, please contact your Breeze Support team or `System Administrator` to review and complete the necessary configurations. Once the lock is removed, you will be able to finalize your order. Your cart items will be saved until you are able to proceed with the checkout process. If you are a `System Administrator`, you can [enable or disable the Order Lock](/docs/tenant-administration/tenant-settings/order-lock.md#enabledisable-order-lock) for the Tenant in the Tenant settings. The error message can look like this depending on the user's language: --- ## Troubleshooting The Troubleshooting section helps you resolve common issues and problems you might encounter while using Breeze. This page provides an overview of available troubleshooting guides and points you to solutions for specific problems. ## What is Troubleshooting? Troubleshooting guides provide step-by-step solutions for common issues that users may encounter. These guides help you quickly identify and resolve problems without needing to contact support, saving you time and getting you back to work faster. **Common Issue Categories:** - **Account Access**: Problems logging in, password resets, and account access - **Email Delivery**: Issues with receiving emails from Breeze - **Order Processing**: Problems with checkout and order placement - **System Access**: Issues with Terms and Conditions and system access ## Available Troubleshooting Guides ### Password Reset If you've forgotten your password or need to reset it, this guide walks you through the process step by step. **Common Scenarios:** - Forgotten password - Need to change your password - Password reset email not received **[View Password Reset Guide](./password-reset.md)** ### Not Receiving Emails If you're not receiving emails from Breeze, this guide helps you and your IT team troubleshoot email delivery issues. **Common Scenarios:** - Emails marked as sent but not received - Emails going to spam or quarantine - Email filtering blocking Breeze emails **[View Email Troubleshooting Guide](./not-receiving-emails.md)** ### Checkout Process Currently Locked If you're seeing an error message that the checkout process is locked, this guide explains why this happens and how to resolve it. **Common Scenarios:** - Tenant not yet approved - Tenant locked due to configuration issues - Unable to complete checkout **[View Checkout Lock Guide](./checkout-process-currently-locked.md)** ### Terms and Conditions Access Issues If you're being redirected to the Terms and Conditions page or having issues accepting terms, this guide explains what's happening and how to proceed. **Common Scenarios:** - First-time access requiring terms acceptance - Updated terms requiring re-acceptance - Unable to proceed past terms page **[View Terms and Conditions Guide](./terms-and-conditions-access.md)** ## Getting Help If you can't find a solution to your problem in these guides, or if you need additional assistance: - **Contact Support**: Reach out to your Breeze support team for help - **System Administrators**: If you're a System Administrator, check the relevant administration sections for configuration options - **Check Documentation**: Browse other documentation sections for feature-specific help ## Common Tasks - Reset a forgotten password - Troubleshoot email delivery issues - Resolve checkout process locks - Handle Terms and Conditions access problems - Understand error messages and their solutions For detailed step-by-step instructions, see the specific troubleshooting guides linked above. --- ## Not Receiving Emails ## Troubleshooting Guide: Missing Emails from Breeze In rare instances, users from certain domains may report not receiving emails from us, even though our email logs show the emails as "sent" and "delivered". Below are steps that your IT team can follow to troubleshoot and resolve this issue. :::note Emails sent from Breeze are sent from the domain `mail.idportal.no` (IP address: `172.246.25.87`). If the email contains any links, the domain `r.mail.idportal.no` may be used as the link address for tracking purposes. The Sender address may vary based on your or your partner's configuration., but will always have one of these domains: - `*@idportal.no` - `*@idportal.se` - `*@idportal.dk` - `*@idportal.fi` - `*@idportal.fr` ::: ### 1. **Check Email Filtering and Security Policies** - **Review Email Filtering Rules**: Ensure that our domain (`mail.idportal.no`) or specific sender email addresses are not being blocked or filtered by your email system at the server level. - **Examine Quarantine or Email Filtering Solutions**: Some security solutions may hold emails in quarantine before they reach users' inboxes. Please check these areas for any emails from us. ### 2. **Whitelist Our Sending Domain** - Add our sending domain (`mail.idportal.no`) to your email system’s whitelist or safe sender list. This action helps prevent our emails from being blocked or flagged as spam. - If possible, also whitelist the IP addresses used by our email provider (`172.246.25.87`) to ensure smooth delivery. - Whitelisting the domain `r.mail.idportal.no` may also help if the email contains links. ### 3. **Verify DNS Records (SPF, DKIM, DMARC)** - Ensure that your domain’s DNS settings include valid **SPF**, **DKIM**, and **DMARC** records. These records are essential for authenticating our emails and preventing them from being rejected or flagged as suspicious. - Tools like [MXToolbox](https://mxtoolbox.com) can be used to check and verify these DNS records. ### 4. **Review Email Server Logs** - Check your email server logs to determine whether our emails are being received, rejected, or otherwise filtered. Server logs may provide error messages or codes that can help identify the cause of the issue. ### 5. **Check Spam or Junk Folders** - Although users may have checked already, it’s important to re-verify that our emails are not ending up in spam or junk folders. Also, ensure that spam filtering is not set to automatically delete messages. ### 6. **Test with Alternative Email Accounts** - If possible, test receiving emails from us using a different email provider (e.g., Gmail, Outlook) to determine if the issue is specific to your domain. ### 7. **Contact Your Email Service Provider** - If the issue persists, please contact your email service provider with details about the problem. They may be able to offer insights or solutions regarding why emails from our domain are not being delivered. ### 8. **Provide Feedback** - If you identify any specific errors or reasons in your logs for the missing emails, please share that information with us. This will allow us to collaborate with our email provider to address the issue more effectively. We appreciate your cooperation in troubleshooting this matter. If you need further assistance, please don’t hesitate to reach out to us. --- ## Password Reset # Password Reset If you’ve forgotten your password or need to reset it, follow these steps to regain access to your Breeze account. This guide will walk you through each step based on the images below. ## Step-by-Step Guide ### 1. Access the Login Screen - Open Breeze and go to the **Login** screen. --- ### 2. Open the Forgotten Password Screen - If you've forgotten your password, click the **Forgotten Password** link. - This will take you to the **Forgotten Password** screen, where you can initiate the reset process. --- ### 3. Request a Password Reset - On the Forgotten Password screen: - Enter your **Email address** in the field provided. - Click **Reset Password** to request a password reset. - You should see a confirmation message indicating that a reset link has been sent to your email. --- ### 4. Check Your Email for the Reset Link - Open your email inbox and look for an email from **Breeze** (check your spam or junk folder if it’s not in your inbox). - The email will contain a link to reset your password. Click on the link to continue. --- ### 5. Create a New Password - After clicking the link, you'll be directed to the **Create a New Password** screen. - Follow the password guidelines for a secure password: - Minimum of 8 characters. - Include at least one letter, one number, and one special character. - Enter your new password and click **Save My New Password**. --- ### 6. Confirm New Password - Once you’ve entered a valid password that meets all security requirements, the guidelines will display green checkmarks. - Click **Save My New Password** to finalize the reset. ### 7. Password Set Confirmation - You should see a confirmation message indicating that your password has been successfully reset. - Click **Login** to return to the login screen and access your account with the new password. --- ### Troubleshooting Tips - **Didn’t receive the reset email?** Check your spam or junk folder. If the email isn't there, wait a few minutes and try requesting a reset again. - **Link expired or not working?** Go back to the **Forgotten Password** screen and request a new reset link. - **Password not accepted?** Ensure that your password meets all security requirements listed on the **Create a New Password** screen. If you encounter further issues, please contact Breeze Support for assistance. --- ## Terms and Conditions Access Issues ## Problem You're being redirected to the Terms and Conditions page and can't access the system, or you're having issues with Terms and Conditions acceptance. ## Why This Happens You'll be redirected to the Terms and Conditions page in these situations: 1. **First-time Access** - You've never accepted the Terms and Conditions before - This is required for all new users 2. **Updated Terms** - The Terms and Conditions have been updated - You need to accept the new version to continue 3. **New Domain Access** - You're accessing a different domain - Each domain requires separate acceptance ## Solution ### If You're Seeing Terms and Conditions for the First Time 1. Scroll through and read the entire document 2. Note the version number at the bottom 3. Choose your action: - Click "Accept" to continue to the system - Click "Decline" if you don't agree (but you won't be able to use the system) ### If You've Been Redirected After an Update 1. Review what's changed in the new version 2. Accept the new terms to regain access 3. You'll be automatically redirected to your original destination ### If You Declined the Terms 1. You'll be logged out of the system 2. To regain access: - Log back in - Review the terms again - Accept them to use the system ## Verification You can verify your acceptance status: 1. Go to your Account Details page 2. Check: - Which version you've accepted - When you accepted it ## Prevention To avoid access issues: 1. Accept terms promptly when presented 2. Review terms carefully before accepting 3. Note that you'll need to accept updates when they occur ## Common Questions ### "Why do I need to accept again?" - Terms have been updated - You're accessing a new domain - Your previous acceptance wasn't recorded ### "What happens if I decline?" - You won't be able to access the system - You can return later to accept ### "Can I use the system without accepting?" No, accepting the Terms and Conditions is mandatory for system access. ## Still Having Issues? If you continue to experience problems: 1. Try these steps: - Clear your browser cache - Log out and back in - Try a different browser 2. Contact support with: - The domain you're trying to access - The version number you're seeing - Any error messages - Screenshots if possible ## Need Help? Contact: - Your system administrator - Technical support - Your organization's legal team (for questions about the terms themselves) --- ## User Administration User Administration in Breeze helps you control who can access the platform, what they can do, and how user accounts are managed throughout their lifecycle. This page gives you an overview of user administration features and points you to detailed guides. ## What is User Administration? User Administration encompasses all the tools and settings you need to manage users in Breeze. This includes controlling access through roles and permissions, managing user accounts, and automating user lifecycle processes to keep your system clean and compliant. **Key Benefits:** - **Access Control**: Define what each user can see and do through flexible role assignments - **Security**: Ensure users only have access to the features and data they need - **Compliance**: Automatically manage user accounts to meet GDPR and other regulatory requirements - **Efficiency**: Streamline user management with automated lifecycle processes ## User Administration Features ### Roles and Permissions Roles are the backbone of access control in Breeze. They determine what each person can see and do in the system—from ordering Credentials to managing entire organizations. The role system is designed to be dynamic and adaptable, allowing you to combine roles to match your exact workflow needs. **Key Features:** - **General Roles**: System-wide permission levels (System Admin, Super Administrator, etc.) - **Task Roles**: Specific capabilities that can be assigned to users (Order Manager, Quality Inspector, etc.) - **Flexible Combinations**: Mix and match roles to create the perfect permission setup - **Granular Control**: Fine-tune access at the Tenant, Domain, or system level ### Life Cycle Management Life Cycle Management allows you to automatically manage the lifecycle of user accounts. This feature helps maintain a clean database and ensures compliance with GDPR policies by automatically handling inactive or unactivated users. **Key Features:** - **Automatic Expiration**: Remove registered users who haven't been activated within a specified timeframe - **Inactivity Management**: Deactivate and delete users who haven't been active for a specified period - **Email Notifications**: Send warnings to users before account deletion - **Domain and Tenant Configuration**: Set defaults at the Domain level with Tenant-specific overrides ## User Administration Features ### OAuth Client Management OAuth Client Management allows system administrators to create and manage OAuth 2.0 clients for machine-to-machine API authentication. This feature provides secure API access provisioning with built-in secret rotation and expiration capabilities. **Key Features:** - Create OAuth clients for tenant users with configurable secret expiration - View and filter OAuth clients by status (Active/Inactive/Revoked) - Update client details (name, description, scopes, status) - Rotate client secrets for enhanced security - Revoke clients when access is no longer needed - One-time secret display with copy-to-clipboard functionality ## Getting Started To learn more about managing users in Breeze, explore the following sections: - **[Roles and Permissions](./roles.md)** - Understand how roles work and find the right role for every team member - **[Life Cycle Management](./life-cycle-management.md)** - Configure automatic user account management and compliance - **[OAuth Client Management](./oauth-client-management.mdx)** - Create and manage OAuth 2.0 clients for API authentication ## Common Tasks - Assign roles to users to control their access - Understand what each role allows users to do - Configure user lifecycle settings for automatic account management - Set up email notifications for account expiration warnings - Customize lifecycle settings at the Domain or Tenant level - Create and manage OAuth 2.0 clients for API authentication - Rotate OAuth client secrets for enhanced security - Revoke OAuth clients when access is no longer needed For detailed instructions on these tasks, see the documentation sections linked above. --- ## Life Cycle Management ## Introduction Life Cycle Management in Breeze allows you to automatically manage the life cycle of existing users. This feature is useful for maintaining a clean database and adhering to GDPR policies. The Life Cycle Management feature allows you to automatically expire registered users who have not been activated within a specified number of days. Any registered user that remains inactive for more than the specified number of days will be deleted. An email notification can be sent to the registered email address X days prior to deletion, warning the user of the impending action and providing an opportunity to activate their account. This feature also allows you to deactivate active users who have not been active for a specified number of days and delete them after a certain number of days after deactivation. All system domains will have a default configuration for Life Cycle Management. However, you can customize the configuration in the Tenant settings. This guide provides instructions on how to configure Life Cycle Management in Breeze. ## Prerequisites Before setting up Life Cycle Management, ensure that you have the necessary permissions to access the Tenant settings in Breeze. ## Default and Tenant-Specific Configuration By default, the Life Cycle Management settings are configured at the `Domain` level. These settings apply universally across all tenants below this domain unless overridden in the `Tenant Settings`. To ensure flexibility, Breeze allows each Tenant to customize their own Life Cycle Management settings according to their specific needs. ### Domain Configuration :::note[Required roles] **Role level**: `System Administrator` **Task Role**: `Domain Administrator` To perform the following steps, you need to have the roles listed above. ::: The `Domain` provides the baseline settings for Life Cycle Management, which include default values for user inactivity periods, warning notifications, and deletion timelines. These settings are automatically applied to all underlying `Tenants` unless they are specifically overridden in the `Tenant Settings`. Domain administrators can configure these settings to align with the organization's policies and compliance requirements. To access and edit the Life Cycle Management settings at the Domain level: 1. **Navigate** to the `Domain Administration` section. 2. **Select** the `Domain` for which you want to configure Life Cycle Management. 3. **Locate** the `User life cycle management` settings and click on the `Change Settings` button. 4. **Follow** the on-screen instructions to access the Life Cycle Management configuration. Read more about the configurable settings below. ### Tenant-Specific Configuration :::note[Required roles] **Role level**: `Super Administrator` To perform the following steps, you need to have the roles listed above. ::: Each `Tenant` in Breeze can override the default `Domain` settings by configuring their own `Life Cycle Management` rules. This is particularly useful for Tenants who may have different compliance requirements or user engagement strategies. To override the default settings and apply tenant-specific configurations: 1. **Navigate** to the `Tenant Settings` section. 2. **Open** the `Life Cycle Management` tab. 3. **Locate** the `User life cycle management` settings and click on the `Change Settings` button. #### Settings details | User Status | Setting | Description | Default Value | |-------------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|---------------| | Registered | [Delete non-activated users after (days)](#delete-non-activated-users-after-days) | Amount of days before non-activated users are deleted. | 90 | | Registered | [Send email warnings before deletion](#send-email-warnings-before-deletion--deactivation) | Check to automatically send email warnings to the registered email. | true | | Registered | [Send first warning before deletion (days)](#send-first-warning-before-deletion--deactivation-days) | Number of days before deletion to send the first warning email. | 70 | | Registered | [Send final warning before deletion (days)](#send-final-warning-before-deletion--deactivation-days) | Number of days before deletion to send the final warning email. | 85 | | Registered | [Send email when user is deleted](#send-email-when-user-is-deleted--deactivated) | Check to send an email to the registered email when the user is deleted. | true | | Registered | [Override receiver for email warnings](#override-receiver-for-email-warnings) | Override the receiver email address for email warnings. | false | | Active | [Deactivate users after (days)](#deactivate-users-after-days) | Amount of days without logging in before active users are deactivated. | 90 | | Active | [Send email warnings before deactivation](#send-email-warnings-before-deletion--deactivation) | Check to automatically send email warnings to the registered email. | true | | Active | [Send first warning before deactivation (days)](#send-first-warning-before-deletion--deactivation-days) | Number of days before deactivation to send the first warning email. | 70 | | Active | [Send final warning before deactivated (days)](#send-final-warning-before-deletion--deactivation-days) | Number of days before deactivation to send the final warning email. | 85 | | Active | [Send email when user is deactivated](#send-email-when-user-is-deleted--deactivated) | Check to send an email to the registered email when the user is deactivated | true | | Active | [Override receiver for email warnings](#override-receiver-for-email-warnings) | Override the receiver email address for email warnings. | false | | Deactivated | [Delete users after (days)](#delete-users-after-days) | Amount of days after deactivation before users are deleted. | 30 | | Deactivated | [Send email warnings before deletion](#send-email-warnings-before-deletion--deactivation) | Check to automatically send email warnings to the registered email. | false | | Deactivated | [Send first warning before deletion (days)](#send-first-warning-before-deletion--deactivation-days) | Number of days before deletion to send the first warning email. | 0 | | Deactivated | [Send final warning before deletion (days)](#send-final-warning-before-deletion--deactivation-days) | Number of days before deletion to send the final warning email. | 0 | | Deactivated | [Send email when user is deleted](#send-email-when-user-is-deleted--deactivated) | Check to send an email to the registered email when the user is deleted. | false | | Deactivated | [Override receiver for email warnings](#override-receiver-for-email-warnings) | Override the receiver email address for email warnings. | false | #### Delete non-activated users after (days) This setting specifies the number of days before non-activated users are deleted from the system. Users who have registered but not activated their accounts within the specified period will be automatically removed from the database. Email warnings will be sent to the registered email address per the configured timeline (first warning and final warning as described below). #### Deactivate users after (days) This setting determines the number of days of inactivity before active users are deactivated. Users who have not logged in for the specified period will be automatically deactivated. Email warnings will be sent to the registered email address per the configured timeline (first warning and final warning as described below). #### Delete users after (days) This setting specifies the number of days after deactivation that users will be permanently deleted from the system. Deactivated users who have not been reactivated within the specified period will be automatically removed from the database. Email warnings will be sent to the registered email address per the configured timeline (first warning and final warning as described below). #### Send email warnings before deletion / deactivation When enabled, this setting will automatically send email warnings to the registered email address before the user is deleted. The email notifications serve as a reminder to the user to perform the necessary actions to prevent their account from being deleted or deactivated. Configure the timeline for sending the first and final warning emails using the `Send first warning before deletion (days)` and `Send final warning before deletion (days)` settings. #### Send first warning before deletion / deactivation (days) This setting determines the number of days before deletion that the first warning email will be sent to the registered email address. The first warning email serves as an initial notification to the user that their account is at risk of being deleted. This number must be less than the `Delete non-activated users after (days)` setting to ensure that the warning emails are sent within the specified timeline. Setting this to `0` will disable the first warning email. #### Send final warning before deletion / deactivation (days) The `Send final warning before deletion (days)` setting specifies the number of days before deletion that the final warning email will be sent to the registered email address. The final warning email serves as a last reminder to the user before their account is permanently deleted. This number must be higher than the `Send first warning before deletion (days)` setting and less than the `Delete non-activated users after (days)` setting to ensure that the final warning email is sent within the specified timeline. Setting this to `0` will disable the final warning email. #### Send email when user is deleted / deactivated When enabled, this setting will send an email to the registered email address when the user status has been changed to `deleted` or `deactivated`. The email notification serves as a confirmation to the user that their account has been removed from the system. Note that deactivated users will be deleted after a specified number of days, as configured in the `Delete users after (days)` setting. :::note Deactivated users can be reactivated by administrators of the `Tenant`. Deleted accounts are permanently removed from the system and cannot be recovered. ::: #### Override receiver for email warnings This setting allows you to specify an alternate email address to receive the warning emails. By default, the registered email address on the user will be used for sending notifications. When enabled, you can enter a custom email address to receive the warning emails. :::important The registered user will not receive any warning emails if this setting is enabled and a custom email address is provided. ::: :::warning The override receiver email address will receive all warning emails, including the first and final warnings. This may result in a spamming of the email address if not managed properly. Ensure that the email address is valid and accessible to the intended recipient. ::: ### Implementation Considerations When configuring Life Cycle Management, it is essential to consider the implications for user experience and compliance with data protection regulations, such as GDPR. Ensure that the configuration aligns with legal requirements and provides users with adequate notice and opportunities to maintain their accounts. Once configured, Life Cycle Management in Breeze will automatically handle the lifecycle of user accounts, keeping your database clean and up to date while ensuring compliance with necessary policies. :::note Any changes to the Life Cycle Management settings may interfere with any ongoing processes. Ensure that the changes are communicated to the relevant stakeholders and users to avoid any disruptions. ::: ## Timeline example Consider the following example to understand how the Life Cycle Management settings work: If this is the setup: Then this will be the timeline: --- ## OAuth Client Management OAuth Client Management allows system administrators to create and manage OAuth 2.0 clients used for machine-to-machine API authentication. This feature provides a secure way to provision API access credentials without using traditional API keys, with built-in secret rotation and expiration capabilities. :::info[Required Role] You must have the **Super administrator** role to access OAuth client management features. The "Manage OAuth Clients" button is only visible to users with `Super administrator` permissions. ::: ## When to Use This Use OAuth client management when you need to: - Enable machine-to-machine API authentication for integrations - Provision secure API access credentials for external systems - Manage API access lifecycle (create, rotate secrets, revoke access) - Replace traditional API key management with OAuth 2.0 client credentials flow This feature is particularly useful for: - Integrating Breeze with external systems that require API access - Setting up automated workflows that need authenticated API calls - Managing API access for multiple integrations or services ## Before You Start - Ensure you have the **Super administrator** role assigned to your user account - Have access to the user profile page for the user you want to create OAuth clients for ## Creating an OAuth Client To create a new OAuth client for a tenant user: 1. Navigate to **Users** page in Breeze 2. Open the profile page for the tenant user who needs API access 3. In the **Actions** section, click **"Manage OAuth Clients"** button 4. In the OAuth client management drawer, click **"Create OAuth Client"** button 5. Fill in the client creation form: - **Client Name** (required): Enter a descriptive name that identifies the purpose of this OAuth client - **Description** (optional): Add any additional context, notes, or information about how this client will be used - **Secret Expiration**: Select the expiration period for the client secret (default: 180 days). Secrets expire automatically for security. You can rotate them before expiration to generate new ones. 6. Click **"Create"** button 7. In the secret display modal: - **Important**: This secret will only be shown once. Make sure to copy it now. - Copy the **Client ID** using the copy button next to the Client ID field - Copy the **Client Secret** using the copy button next to the Client Secret field - Store both values securely (they will be needed for API authentication) - Check the **"I have saved this secret securely"** checkbox - Click **"Close"** button to close the modal ![OAuth client management drawer empty state](_images/dii-001-oauth2-management-drawer-empty.png) _The OAuth client management drawer showing the empty state with the "Create OAuth Client" button visible._ ![Create OAuth client form](_images/dii-001-oauth2-create-client-form.png) _The create OAuth client form with fields for Client Name, Description, and Secret Expiration._ After creation, the new OAuth client appears in the client list with status "Active". The client secret cannot be retrieved again after the modal is closed, so ensure you save it securely. ## Viewing and Managing OAuth Clients The OAuth client management drawer displays all OAuth clients associated with the current tenant user. ### Viewing the Client List 1. Open the OAuth client management drawer from a user's profile page (see steps 1-3 in "Creating an OAuth Client") 2. View the list of OAuth clients for the tenant user The list shows the following information for each client: - **Client Name**: The name you assigned when creating the client - **Client ID**: The unique identifier for the OAuth client (truncated in the list view) - **Status**: Current status (Active, Inactive, or Revoked) - **Created**: Date when the client was created - **Last Used**: Date when the client was last used for authentication (or "Never used") - **Expires At**: Expiration information (e.g., "Expires in 180 days") ![OAuth client list](_images/dii-001-oauth2-client-list2.png) _The OAuth client list showing created clients with search and filter options, including status badges and action buttons._ ### Searching and Filtering - **Search**: Use the search field to filter clients by name or client ID - **Status Filter**: Use the status filter dropdown to filter by status: - **All**: Show all clients regardless of status - **Active**: Show only active clients - **Inactive**: Show only inactive clients - **Revoked**: Show only revoked clients ### Viewing Client Details Click on a client row in the list to view detailed information about that client, including full client ID, description, scopes, and additional metadata. ## Updating OAuth Client Details You can update an existing OAuth client's information: 1. Open the OAuth client management drawer from a user's profile page 2. Click on an OAuth client in the list to view details 3. Click **"Edit"** or similar action button 4. Update the client information: - **Client name**: Change the name to better reflect the client's purpose - **Description**: Update or add description text - **Scopes**: Modify the OAuth scopes associated with the client - **Status**: Change status between Active and Inactive 5. Save the changes Changes are reflected immediately in the client list and detail view. ## Rotating Client Secrets Rotate a client secret when: - The secret may have been compromised - You want to refresh credentials for security best practices - The secret is approaching expiration and you want to generate a new one To rotate a client secret: 1. Open the OAuth client management drawer from a user's profile page 2. Select an OAuth client from the list 3. Click **"Rotate Secret"** or similar action button 4. Confirm the rotation action in the confirmation dialog 5. In the secret display modal: - **Important**: The new secret will only be shown once. Make sure to copy it now. - Copy the new **Client Secret** using the copy button - Store the new secret securely - Check the **"I have saved this secret securely"** checkbox - Click **"Close"** button to close the modal **Important**: When you rotate a secret: - The old secret is **immediately invalidated** and cannot be used for authentication - Any integrations using the old secret will stop working until they are updated with the new secret - The new secret is displayed once and cannot be retrieved again after the modal is closed ![Secret display modal](_images/dii-001-oauth2-secret-display-modal.png) _The secret display modal showing Client ID and Client Secret with copy buttons and the confirmation checkbox that must be checked before closing._ ## Revoking OAuth Clients Revoke an OAuth client when: - The client is no longer needed - Access should be permanently disabled - A security incident requires immediate access termination To revoke an OAuth client: 1. Open the OAuth client management drawer from a user's profile page 2. Select an OAuth client from the list 3. Click **"Revoke"** or similar action button 4. Confirm the revocation action in the confirmation dialog 5. Verify the client status changes to "Revoked" **Important**: When you revoke a client: - The client secret is **immediately invalidated** and cannot be used for authentication - Any integrations using this client will stop working - The client remains visible in the list but is marked as "Revoked" - Revoked clients cannot be reactivated ## Expiry Warning Emails Breeze automatically sends email notifications before your OAuth client secrets expire. This helps prevent service disruptions by alerting you to rotate secrets proactively. ### How It Works The system sends up to **5 warning emails** per client at these intervals: - **30 days before expiry** (if expiry is more than 30 days away) - **14 days before expiry** (if expiry is more than 14 days away) - **7 days before expiry** (if expiry is more than 7 days away) - **1 day before expiry** (if expiry is more than 1 day away) - **On expiry day** (0 days before) **Smart Scheduling:** The system only sends warnings that are applicable. For example: - If a client expires in 3 days, you'll receive the 1-day warning and the on-expiry warning - If a client expires in 60 days, you'll receive all 5 warnings ### Who Receives Warnings Warning emails are sent to: 1. **User** - The user account associated with the OAuth client (the account that determines permissions) 2. **Creator** - The admin user who created the client (if different from the User) If the User and Creator are the same person, only one email is sent. ### Email Content Each warning email includes: - **Subject**: "Your OAuth Client Secret is Expiring Soon" - **Client Information**: Client name and tenant name - **Expiration Details**: - Formatted expiration date - Days remaining until expiration (or "expired" if on expiry day) - **Action Link**: Direct link to OAuth client management page in the portal - **Localization**: Available in multiple languages (English, Norwegian, Swedish, French, Finnish, Danish) ### When Warnings Stop Warnings are automatically disabled when: - Client status changes to `inactive` - Client status changes to `revoked` - All warning stages have been sent - Client secret is rotated (a new expiration date triggers a new warning schedule) ### Best Practices **For Administrators:** - Monitor your email inbox for expiry warnings - Rotate secrets promptly when warnings are received - Don't wait until the last warning to rotate - Verify email addresses for User/Creator are correct - Check spam folders if warnings are not received ### Troubleshooting Warnings **Not Receiving Warnings:** - Check that client status is `active` (inactive/revoked clients don't receive warnings) - Verify User/Creator have valid email addresses - Check spam/junk folders - Contact your system administrator to verify the warning system is running **Receiving Too Many Warnings:** - This is normal - you'll receive up to 5 warnings per client - Warnings stop automatically after all stages are sent - Rotating the secret will reset the warning schedule **Warnings for Expired Clients:** - If a client expires, you'll receive the on-expiry warning - Rotate the secret immediately to restore access - A new expiration date will trigger a new warning schedule ## Important Considerations ### Secret Security - **One-time display**: Client secrets are displayed only once after creation or rotation. They cannot be retrieved again after the modal is closed. - **Secure storage**: Always store client secrets securely. Never commit them to version control or share them insecurely. - **Confirmation required**: The secret display modal requires you to confirm that you have saved the secret securely before you can close it. ### Secret Expiration - Secrets expire automatically based on the expiration period set during creation (default: 180 days) - You can rotate secrets before expiration to generate new ones - Expired secrets cannot be used for authentication - Monitor the "Expires At" column in the client list to track expiration dates - **Automatic email warnings** are sent before expiration (30, 14, 7, 1 days before, and on expiry day) - Respond to expiry warning emails promptly to avoid service disruption ### Access Control - Only users with `Super administrator` role can access OAuth client management - The "Manage OAuth Clients" button is only visible to `Super administrators` - OAuth clients are associated with specific users - Each user can have multiple OAuth clients ## What's Next? - [Roles and Permissions](./roles.md) - Learn about user roles and permissions in Breeze - [User Administration Overview](./index.mdx) - Explore other user administration features - [OAuth API Authentication](/docs/authentication/oauth-api-authentication) - Learn how to use OAuth 2.0 clients for API authentication --- ## Roles and Permissions ## What are roles? Roles are the backbone of the Breeze platform. They control what each person can see and do in the system—from ordering an ID card to managing entire organizations. Think of roles as your access control system, but much more flexible and powerful than traditional permission models. The role system in Breeze is designed to be **dynamic and adaptable**. Whether you're a small organization with a few administrators or a large enterprise managing multiple tenants across different sites, roles can be combined and configured to match your exact needs. This means you can create the perfect permission setup for your workflow, not the other way around. Each role has a clear purpose and comes with specific capabilities. When you understand what each role does, you can confidently assign the right permissions to the right people—ensuring everyone has access to what they need, nothing more, nothing less. ## General roles These are the main permission levels in Breeze. Think of them as your foundation—they determine the overall scope of what someone can do. ### System Admin (`systemAdmin`) **What it means:** System Admins are the architects of your Breeze setup. They control production sites and system-wide settings, manage card template layouts, domains, user groups, and production workflows. If it affects how the system works across all sub-tenants, a System Admin manages it. **What they can do:** - Access Templates, Production, and Domain Administration modules - Create and update card templates, configure card layouts - Set template field rules and translations - Manage user groups - Configure domain-level features (AMR transfer, mobile credentials, local production) - Control order states - Download Credential data exports - Mark orders as shipped/invoiced - Remove photo backgrounds in bulk - Manage quality check workflows - Configure production site settings - Manage number ranges across tenants - Access production job lists - Configure external data sources **Who should get this:** Production site managers, template designers, and system operators who handle production workflows, template design, and system configuration. ### Super Administrator (`superAdmin`) **What it means:** Super Administrators manage orders, tenant configuration, user groups, and production operations. They control order workflows, tenant features, and can operate production when they have the appropriate task role. They're the power users who keep everything running smoothly at the tenant level. **What they can do:** - Access Tenant Settings, Order History, and Production modules - Prepare orders for production from the pending production list - Cancel orders - Change order states (shipped, invoiced, partly shipped) - Enable tenant features (local production, mobile credentials, Duo ID) - Configure tenant delivery settings - Manage user groups - View users in user groups - Access tenant statistics dashboard - Operate production (mark Credentials as produced, update production data) when they have the `productionOperator` task role - Manage tenant product availability - Configure tenant checkout flows - Manage tenant approvals settings **Who should get this:** Order managers, tenant administrators, production operators, and those who configure order workflows and tenant settings. ### Administrator (`admin`) **What it means:** Administrators handle the day-to-day administration for an organization (tenant). They manage users, Credentials, and approvals within their organization. This is the go-to role for people who keep things organized and running on a day-to-day basis. **What they can do:** - Access Users, Credentials, and Approvals pages - Activate/deactivate Credentials that are connected to access systems - View and edit Credential details - Modify Credential data (with `dataChangeOperator` role) - Manage users (invite, assign roles, modify user groups, activate/deactivate, move between tenants with `userAdministration` role) - Approve/reject Credential requests and Duo ID submissions (with `approver` role) - View order history (with `viewOrderHistory` role) - Create identities (with `identityCreator` role) - Manage number ranges for their tenant (with `numberRangeAdmin` role) - Access the My Requests page to handle pending approvals **Who should get this:** Local administrators in each organization or department. ### User (`user`) **What it means:** Users are the people who actually use the system to order and manage their own Credentials. They can create Credentials and manage their own information. This is the standard role for anyone who needs an ID card. **What they can do:** - Access Cart, My Orders, and My Profile pages - Create and submit Credential requests through the checkout process - Upload photos and signatures - Track Credential status in My Orders - View Credential previews - Complete Duo ID registration forms - Upload photos via webcam or file upload - Manage delivery addresses - View order tracking information - Access personal sign-in history **Who should get this:** Staff members who need ID cards or mobile IDs. ## Task roles Task roles are specialized permissions that give people specific capabilities beyond their general role. Think of them as add-ons that let you fine-tune what someone can do. Task roles are organized by the minimum role level required to have them. ### Quality Inspector (`qualityInspector`) **Required role level:** `systemAdmin` **What it means:** Quality Inspectors are the final checkpoint before cards ship. They inspect physical cards after production, approving cards that pass quality checks or rejecting them back to production. This role keeps quality standards high. **What they can do:** - View the Quality Check page in Production module - Review produced cards in "quality_check" status - Use the "Quality check" button on individual Credentials - Approve cards that are correct (moves them to "produced" status) - Reject cards that have issues (sends them back to "in_production" with a rejection reason) - Access batch quality check dialogs for batch orders - View credential previews during quality inspection **Who should get this:** Quality assurance staff at production sites who verify cards before they're shipped. --- ### Warehouse Operator (`prodSiteWarehouse`) **Required role level:** `systemAdmin` **What it means:** Warehouse Operators manage order fulfillment and shipping at a production site. They control when orders are marked as shipped and can add items to orders. They're the people who make sure orders get out the door. **What they can do:** - Access order detail pages - Use "Mark as Shipped" and "Mark as Partly-Shipped" buttons on orders in "packing" status - Add items to existing orders using the "Add product" button - Download delivery lists - View and manage order delivery details - Manage order states related to delivery and shipping **Who should get this:** Warehouse and dispatch staff at production facilities. --- ### Invoicing Operator (`prodSiteInvoice`) **Required role level:** `systemAdmin` **What it means:** Invoicing Operators mark orders for invoicing at a production site. They record billing information for completed orders and make sure the financial side of production is handled correctly. **What they can do:** - Access order detail pages - Use "Set status: Invoiced" button on orders - Set invoice dates and references in the invoice details section - View invoice reference information - Calculate billing basis for orders - Mark completed orders as ready for invoicing **Who should get this:** Finance staff at production sites who handle invoicing. --- ### Production - Create Layouts (`prodLayoutCreator`) **Required role level:** `systemAdmin` **What it means:** Layout Creators design and maintain card template layouts. They create the visual design that appears on physical ID cards. This is where the look and feel of your cards comes from. **What they can do:** - Access Templates → Card Layouts - Create new card layouts using CardSDK Designer - Copy layouts between tenants - Edit front and back page layouts - Configure field placements and order - Set image rules (photo placement, aspect ratios) - Configure background removal settings (transparent or color modes) - Manage template field rule sets - Set logo placements and sizes - Configure text styling and translations - Preview layouts before saving **Who should get this:** Graphic designers and print specialists who design ID cards. --- ### Manage Templates - Mobile Credential (`tplMobileCredential`) **Required role level:** `systemAdmin` **What it means:** This role manages mobile ID templates and mobile provider connections. They control how mobile IDs are issued and synced with mobile providers. If you're using mobile credentials, this person makes sure everything stays connected. **What they can do:** - Access Templates → Mobile Credential Templates page - Create and update mobile Credential templates - Configure mobile provider connections (STid, etc.) - Test mobile provider connections using "Check Connection & Credits" button - Trigger manual syncs using "Sync now" button - Configure sync schedules (cron strings) - Set provision methods and sync settings - Manage duplicate vCard handling strategies - Configure sync image settings - View mobile credential status and sync history - Configure mobile ID template field settings **Who should get this:** Mobile ID administrators who set up and maintain mobile Credential templates. --- ### Manage Templates - AMR Requests (`tplAmrRequest`) **Required role level:** `systemAdmin` **What it means:** AMR Request template managers configure how Credential data is sent to access control systems (AMR - Access Management Requests). They control what data is sent when Credentials are activated. This is the bridge between Breeze and your access control systems. **What they can do:** - Access Templates → AMR Request Templates page - Create and update AMR request templates - Configure which Credential fields are sent to access systems - Set field mappings using the field mapping editor - Configure email recipients and templates for AMR requests - Set approval requirements for access requests - Test AMR request configurations - View AMR request template details - Manage AMR request template availability **Who should get this:** IT staff who integrate Breeze with access control systems (door readers, parking systems, etc.). --- ### Domain Administrator (`domainAdministrator`) **Required role level:** `systemAdmin` **What it means:** Domain Administrators manage domain-level features and integrations. They enable advanced features and connect external data sources. They're the ones who unlock new capabilities for the entire domain. **What they can do:** - Access Domain Administration module - Enable/disable AMR transfer features for the domain - Enable/disable mobile credentials feature - Enable/disable local production feature - Enable/disable external data sources feature - Enable/disable Duo ID feature - Configure domain-level feature settings - Manage AMR Transfer Templates at domain level - Configure external data sources that can feed into templates - Manage domain-level approvals settings - Configure domain default settings for tenants **Who should get this:** IT administrators at the domain level who configure integrations and enable platform features. --- ### Product Maintainer (`productMaintainer`) **Required role level:** `systemAdmin` **What it means:** Product Maintainers keep the product catalog up to date. They define what card types, encoding options, and services are available when people order Credentials. They're the ones who make sure the right products are available at the right time. **What they can do:** - Access Product Administration page - Create new products with product details forms - Update product definitions (card types, encoding, printing options) - Set product pricing and availability - Manage product availability in domains - Configure transportation methods for products - Set product descriptions and previews - Deactivate products when they're no longer available (with confirmation dialog) - Manage domain default products - View product usage across tenants **Who should get this:** Product managers or operations staff who maintain the catalog of available Credential products and services. --- ### Data Exporter (`dataExporter`) **Required role level:** `systemAdmin` **What it means:** Data Exporters generate reports by exporting Credential and access group data. They create the data exports needed for reporting and compliance. When you need to analyze what's happening or prove compliance, this role has you covered. **What they can do:** - Access Credentials list page - Use "Download to Excel" button to export Credential data - Export search results with filters applied - Export access group information from Access Control pages - Generate compliance reports with Credential details including production dates and status - Export data with custom field selections - Download CSV files with Credential information for analysis **Who should get this:** Analysts, compliance officers, and auditors who need to export Credential data. --- ### Tenant Statistics (`tenantStatistics`) **Required role level:** `superAdmin` **What it means:** This role provides read-only access to analytics and usage data for tenants. People with this role can view statistics and metrics but can't make changes. Perfect for leadership and analysts who need insights without access. **What they can do:** - Access Tenant Statistics page - View usage dashboards with charts and metrics - See tenant activity statistics (credentials ordered, produced, users created, tenants created) - View performance metrics and trends - Filter statistics by date ranges - View statistics across multiple tenants - Export statistics data **Who should get this:** Leadership, analysts, or auditors who need to review tenant usage data. --- ### Tenant Creation (`tenantCreation`) **Required role level:** `superAdmin` **What it means:** Tenant Creators set up new organizations (tenants) in the system. They provision new organizations with default settings and get them ready to use. They're the first step in onboarding new organizations. **What they can do:** - Access Tenants page - Use "Create a new tenant" button - Fill out tenant creation form with tenant name, description, and settings - Set up default configuration for new organizations (delivery settings, features, products) - Assign initial administrators and user groups - Configure tenant contact information - Save new tenant to the system **Who should get this:** Platform onboarding staff who set up new organizations in Breeze. --- ### Tenant Deletion (`tenantDeletion`) **Required role level:** `superAdmin` **What it means:** Tenant Deletion role holders safely retire and remove tenants from the system. They handle tenant decommissioning following proper policies. This is a sensitive role that should be carefully managed. **What they can do:** - Access tenant detail pages - Use tenant deletion functionality (when available) - Delete tenants that are no longer needed through confirmation dialogs - Perform tenant cleanup following policy - Verify tenant dependencies before deletion **Who should get this:** Platform offboarding staff who handle tenant retirement. --- ### Production Operator (`productionOperator`) **Required role level:** `superAdmin` **What it means:** Production Operators handle the physical production of ID cards. They mark Credentials as produced and update production information. These are the people who actually make the cards happen. **What they can do:** - Access Production → Produce page - View credentials ready for production - Select credentials to produce - Use "Produce Credential" button on individual credentials - Mark credentials as produced after printing/encoding through production dialogs - Update production dates and device information - Upload card preview images (front and back) - Edit photos during production - Modify credential data in production mode - Print carrier-only when applicable - View production job lists - Use batch production features with delay settings **Who should get this:** Print room operators, card encoding technicians, and production staff who physically create ID cards. --- ### Access Controller (`accessController`) **Required role level:** `admin` **What it means:** Access Controllers manage access groups that control which Credentials can access which resources. They control access permissions for Credentials in access control systems. This role connects your cards to your access control systems. **What they can do:** - Access Access Control pages (when available) - Create and manage access groups through access group management interfaces - View access group usage and membership - Configure which Credentials belong to which access groups (indirectly, by managing access group definitions) - View access right assignments - Manage access group settings **Who should get this:** Security administrators who manage access permissions for Credentials in access control systems. --- ### User Administration (`userAdministration`) **Required role level:** `admin` **What it means:** User Administrators manage user accounts and role assignments. They control who has access to Breeze and what they can do. They're the gatekeepers of access in your organization. **What they can do:** - Access Users page - Use "Create a new User" button to invite users via email - Open user profile pages - Modify user roles through "Modify user roles" drawer (assign base roles and task roles) - Add/remove users from user groups - Activate/deactivate user accounts using action buttons - Re-activate deactivated users - Delete user accounts (with email confirmation) - Move users between tenants (when available) - Send activation emails - Resend activation links - View user sign-in history **Who should get this:** Tenant administrators or helpdesk supervisors who manage user access. --- ### Identity Creator (`identityCreator`) **Required role level:** `admin` **What it means:** Identity Creators create and maintain person profiles (identities) that Credentials are linked to. They set up the person records that Credentials represent. They build the foundation that Credentials are built on. **What they can do:** - Create new identities (person profiles) through identity creation forms - Update identity information in credential data collections (names, photos, contact details) - Upload person photos and signatures - Edit person details in Credential edit dialogs - Link Credentials to identities when creating credentials - Manage identity data before credential issuance **Who should get this:** HR staff, helpdesk teams, or administrators who create person records before Credentials are issued. --- ### Number Range Administration (`numberRangeAdmin`) **Required role level:** `admin` **What it means:** Number Range Administrators manage numbering sequences used for Credentials. They control how Credentials get their unique numbers. This role ensures every Credential follows your organization's numbering scheme. **What they can do:** - Access Number Ranges page - Create and configure number range templates - Set number prefixes, suffixes, and site codes - Configure incremental steps and minimum lengths - Set version number starting points - Whitelist tenants to use specific number ranges through tenant selection - View next unused numbers - Manage number range formulas - View tenants using each number range - Remove number ranges from tenant whitelists **Who should get this:** Operations staff responsible for ensuring Credentials follow the correct numbering scheme. --- ### Approver (`approver`) **Required role level:** `admin` **What it means:** Approvers review and approve Credential requests and Duo ID submissions. They control whether Credentials proceed to production. They're the quality gatekeepers who make sure requests meet standards before cards are made. **What they can do:** - Access Approvals page and My Requests page - View pending approval requests in approval review dialogs - Use "Approve" and "Reject" buttons on approval items - Review credential previews during approval - Reject requests with rejection reasons through rejection dialog - Approve Duo ID submissions when collaborators submit their details - View Duo ID approval review dialogs with credential previews - Resend Duo ID invitation emails using "Send Duo ID request to end-user again" button - Navigate between pending items in approval workflows - View approval request history and status **Who should get this:** Managers, supervisors, or designated approvers who must sign off on Credential requests before production. --- ### View Order History (`viewOrderHistory`) **Required role level:** `admin` **What it means:** This role provides read-only access to historical order information. People with this role can view past Credential orders but can't create or modify them. Perfect for people who need to review history without making changes. **What they can do:** - Access Order History page - View past orders in order list - Filter orders by date range or status using filters - Open order detail pages to see order details and history - View order items and delivery information - See order status timeline - Download order information - View order tracking details (read-only, cannot modify orders) **Who should get this:** Finance staff, auditors, or team leads who need to review order history but don't need to create or modify orders. --- ### Data change operator (`dataChangeOperator`) **Required role level:** `admin` **What it means:** Data Change Operators update Credential data after creation. They make controlled corrections to Credential information when needed. This role is for fixing mistakes and keeping data accurate. **What they can do:** - Access Credential detail pages - Use "Modify Credential Data" button on credentials - Open credential data modification dialogs - Update data collections linked to credentials (person names, photos, contact details) - Edit person information fields - Upload new photos to replace existing ones - Correct errors in credential data through edit forms - Make approved data changes with confirmation - View credential modification history **Who should get this:** Senior operators who are authorized to make data corrections when mistakes are discovered or updates are needed. --- ## How role assignment works Understanding how roles are assigned helps you plan your access control strategy. Here's how it works: ### Who can assign roles? To grant any role or task role, the acting user must: - Have role level: `admin` or higher - Have task role: `userAdministration` - Not assign a role with higher priority than their own (you can only grant roles at or below your own priority level) - Perform the action within the correct tenant context ### Minimum role requirements for task roles Task roles are assigned based on priority values. You must have at least the role level with a priority equal to or higher than the task role's priority to receive it: - Task roles with priority 201 require: `systemAdmin` (priority 100) or higher - Task roles with priority 401–410 require: `superAdmin` (priority 400) or higher - Task roles with priority 501 require: `admin` (priority 500) or higher This ensures that people can only assign roles that match or are below their own level, maintaining proper security and access control throughout the system.