Home All Handbooks OAuth / OpenID SSO

User Profile Mapping

The User Profile section allows you to control how user details from your OAuth/OpenID Connect (OIDC) provider are applied to accounts in your Atlassian application after a successful SSO login. This enables automatic user attribute synchronization and accurate identity mapping between your IdP and Atlassian instance.

Overview

During an OAuth/OpenID Connect SSO flow, the identity provider returns a set of user attributes (such as username, email, first name, last name, phone, etc.) in the authentication response. The User Profile tab lets you:

• Map those attributes from the provider to the appropriate fields in the Atlassian user profile.
• Automatically update or provision user accounts in your Atlassian application based on the mapped data.
• Extract specific values using custom patterns (for example, using regular expressions).
• Extend synchronization to additional custom user properties.

Throughout this section, “response” refers to the OAuth/OIDC response returned by your identity provider, and “provider” refers to the configured OAuth/OIDC identity provider.

Key Features and Configuration Settings

User Profile Synchronization

Enable this option if you want the profile attributes of existing users to be updated every time they authenticate via SSO.

• Enabled: Updates user attributes in the Atlassian application whenever the OAuth/OIDC provider returns new values.
• Disabled: Leaves existing profile data unchanged, regardless of the SSO response.

Note: If your user directory is read-only (for example, LDAP with no write permission), keep this option disabled to prevent update errors.

Login User Account Using Username or Email

This setting determines how the plugin matches the user in the Atlassian application:

• Username: The plugin will look for a match based on the username attribute received from the provider.
• Email: Allows login matching by email address.

Important: Atlassian systems can allow multiple accounts with the same email address, so using username matching is recommended where possible. If no existing user is found based on the selected attribute, a new user account will be created automatically.

Attribute Mapping

Attribute mapping tells the plugin how to translate provider claims into Atlassian user profile fields.

You must specify the attribute names from the OAuth/OIDC response that correspond to these Atlassian fields:

• Username: The attribute whose value should be used as the user’s username in the Atlassian application.
• Email: The attribute that contains the user’s email address (required if email login is enabled).
• Full Name / First Name / Last Name: Depending on how your provider returns user names, you can map a combined full name or separate first and last name fields.

If no attribute is mapped, the plugin will fall back to using the email address (if available) to identify the user.

Regular Expression (Regex) Extraction

If the username isn’t directly available or must be derived from another attribute (like email), you can enable a regular expression (regex) to extract it.

How it works:

• Enter the attribute name that contains the raw value (for example, the email).
• Enable the regex option.
• Provide a regex pattern to extract the desired substring.
• Test the regex using sample input to verify the output.

Example Use Case:

Extract username from email using this regex: ^.*?(?=@).

If the email is user@example.com, the extracted username will be user.

Separate Name Attributes

Use this option when your identity provider returns first and last name as individual attributes instead of a single full name value.

• Disabled: Only the full name field is used.
• Enabled: The plugin allows separate mapping for First Name and Last Name.

Extended User Properties (Custom Attributes)

If your OAuth/OIDC provider returns additional attributes (such as department, phone number, location, etc.), you can map them to corresponding user properties in the Atlassian application.

This allows for richer user profiles and more accurate identity representation inside Jira or other Atlassian tools.

Summary

The User Profile tab is essential for synchronizing identity data between your OAuth/OIDC provider and Atlassian applications. It supports flexible mapping, automated updates or provisioning, and advanced extraction logic to ensure users are correctly identified and onboarded during the SSO process.

Home All Handbooks OAuth / OpenID SSO

Advanced Settings

The Advanced Settings section allows administrators to fine-tune the behavior of OAuth/OpenID Single Sign-On (SSO) for Atlassian applications. These settings provide greater control over user provisioning, request customization, token validation, and overall security of the authentication flow.

Use these options when you need more flexibility beyond the basic SSO configuration.

Enable PKCE (Proof Key For Code Exchange)

Enable PKCE to add an extra layer of security to the OAuth/OIDC Authorization Code flow.

PKCE protects against authorization code interception attacks by binding the authorization request and token exchange together.

When PKCE is enabled:

• A secure code verifier is generated by the client
• A derived code challenge is sent with the authorization request
• The Identity Provider validates the code verifier during token exchange

PKCE is highly recommended in the following scenarios:

• When the client secret cannot be securely stored
• When stronger protection against interception attacks is required
• When following modern OAuth 2.0 and OIDC security best practices

User Creation Settings

• Allow User Creation

Enable this option to automatically create a new user in the Atlassian application when the user successfully authenticates via OAuth/OIDC SSO for the first time. If this option is disabled, only users who already exist in the Atlassian application will be allowed to log in through SSO.

Note: User creation is not supported for read-only directories by default. Ensure that the selected directory allows user creation.

• Directory for New Users

When a new user is created through SSO, this setting determines which user directory the account will be added to. You can select an existing internal directory or any connected external directory based on your user management requirements.

If no suitable directory exists, you also have the option to create a new internal directory directly from this page and assign newly created SSO users to it.

• Remote Directory Sync

Enable this option to synchronize user information from a remote directory during SSO login. If the user already exists in a linked external directory, their user attributes are updated automatically at the time of authentication.

Note: This option applies only to Crowd directories. Ensure that the Crowd directory is properly configured and connected to the Atlassian application before enabling Remote Directory Sync.

Request Parameter Configuration

• ACR Value

The Authentication Context Class Reference (ACR) value is sent to the Identity Provider as part of the authentication request. This allows you to request a specific authentication level, such as multi-factor authentication or conditional access policies, if supported by your Identity Provider.

• State Parameter

The state parameter is used to protect against Cross-Site Request Forgery (CSRF) attacks. A unique state value is generated with each authorization request and validated when the response is received. This parameter is enabled by default and is strongly recommended for all OAuth/OIDC integrations.

• Add Custom Parameters

This option allows you to include additional parameters in the authorization request. Custom parameters are often required for provider-specific configurations such as prompt behavior, login hints, nonce values, or custom policy enforcement.

Token And Response Validation

• Check Issuer in Response

Enable this option to validate the issuer (iss) claim present in the authentication response or ID token. When enabled, the plugin verifies that the issuer value matches the expected Identity Provider, helping prevent token substitution and misconfiguration-related security issues.

You can choose between the following options:

• Default
  When selected, the issuer is automatically validated against the Identity Provider configuration defined in the plugin. This is recommended for most standard OAuth/OIDC setups.
• Custom
  Select this option to manually specify a custom issuer value. This is useful in advanced scenarios where the issuer in the response differs from the standard provider configuration or when using custom or multi-tenant Identity Provider setups.

• Public Key

A public key is a fundamental component of asymmetric cryptography and is used to verify digitally signed data. OpenID Connect (OIDC) Providers sign all issued tokens using a private key, and the corresponding public key is used by the application to validate those tokens.

Provide the public key issued by your OpenID Connect Provider in this field to verify the digital signature of ID tokens received during authentication. This validation confirms the identity of the Identity Provider and ensures that the token has not been altered or tampered with in transit.

• JWKS Endpoint URL

The JSON Web Key Set (JWKS) is a collection of public keys published by the authorization server and used to verify JSON Web Tokens (JWTs). Instead of manually configuring public keys, you can specify a JWKS endpoint URL provided by your Identity Provider.

When configured, the plugin automatically retrieves the signing keys from the JWKS endpoint and uses them to dynamically validate JWT tokens included in the authentication response. This approach simplifies key management and ensures seamless token validation, especially when the Identity Provider rotates signing keys.

Summary

The Advanced Settings provide administrators with powerful controls to manage and optimize the OAuth/OIDC Single Sign-On experience for Atlassian applications. These settings enable seamless user provisioning and synchronization, allow fine-grained customization of authorization requests, ensure secure validation of authentication tokens, and enhance overall security through features such as PKCE. Together, these capabilities help deliver a secure, flexible, and enterprise-ready SSO implementation that aligns with modern identity and access management best practices.

Home All Handbooks OAuth / OpenID SSO

SSO Settings

SSO Setting tab Control how your users and administrators login using SSO. The settings in SSO Settings tab define the user experience for Single Sign On.

You can Perform following operations on SSO setting tab :

• Sign In Settings
• Redirection Rules
• Session Management
• Look and Feel
• Post Logout Configurations
• Global SSO Settings
• Backup and Restore

Home All Handbooks OAuth / OpenID SSO

Sign-In Settings

The Sign-In Settings section allows administrators to control how authentication is initiated and managed when users access the Atlassian application through OAuth/OpenID Connect (OIDC). These settings define the login redirection behaviour, fallback access methods, administrator protection mechanisms, and post-login navigation.

Relay State (Return URL/Post-Login Redirect URL)

Return URL :

The Relay State specifies where users are redirected after successful SSO.

• If configured: Users are always redirected to the specified URL after login.
• If not configured: Users are returned to the resource or page they originally requested.

Example:

Administrators commonly use this setting to send users to a dashboard or a dedicated landing page.

Custom Redirect for New & Reactivated Users

This Relay State setting redirects newly created or reactivated users to the specified URL after successful SSO.

Login Restriction

Allowed Domains:

This feature allows authentication only for users whose email addresses belong to approved domains.

• Provide one or more domains separated by commas.
• Users with email addresses outside these domains will not be allowed to do SSO.

Regex-Based Login:

This setting allows administrators to control which users are permitted to log in by validating their usernames against a defined regular expression pattern.

Only users whose usernames match the configured regex will be allowed to authenticate. Any user whose username does not satisfy the pattern will be denied access.

NOTE:

This feature depends on the Username attribute mapping configured in the User Profile tab.

If the Username Attribute is not mapped, the plugin will not have a value to evaluate, and the regex restriction will not take effect.

Example: If the regex is ^admin.*, only usernames that start with admin will be allowed to log in.

Bypass SSO for Specific URLs

This feature allows you to exclude certain URLs from the SSO flow. Users who access the specified paths will bypass Single Sign-On and will be redirected to the default Atlassian login page instead.

Enter the URL pattern to be excluded.

Example: /secure/ViewProfile.jspa

Restrict Access

When this option is enabled, any unauthenticated attempt to access public Jira pages will automatically redirect the user to the login page for SSO.

Auto-Redirect to Application

Enable this to force users to authenticate via SSO only, bypassing the default login page completely.

• Users are immediately redirected to the configured OAuth/OIDC Provider’s login screen upon accessing the Atlassian login page.
• This is essential in environments where local credentials should not be used.
• Useful for enforcing strict corporate authentication policies.

Enable AutoRedirect Delay

Delays the redirect to the provider by showing a progress bar. Recommended when testing SSO rollout

• Allows users to cancel immediate redirection to the provider and log in with local credentials.

Backdoor / Emergency Login

Enable Backdoor Login

This enables a separate login path (Emergency URL) that bypasses SSO. Recommended for all production environments

• Ensures admins can regain access if SSO is misconfigured, unavailable, or the provider is down.
• You can restrict access to the emergency URL to specific groups only.

Important: Always document your emergency URL securely and restrict it to trusted administrators.

Restrict Backdoor Access

You can limit which groups are allowed to use the emergency login. Highly recommended for security compliance.

• Only members of the specified groups will be able to access the backdoor URL.
• All other users must complete SSO through the provider.

This prevents misuse of the fallback mechanism.

Jira Service Management (JSM) Specific Auto-Redirection Settings

Enable this to force users to authenticate via SSO only, bypassing the default login page for JSM.

• Users are immediately redirected to the configured OAuth/OIDC Provider’s login screen upon accessing the Atlassian login page.
• This is essential in environments where local credentials should not be used.

Enable AutoRedirect Delay

Delays the redirect to the provider by showing a progress bar.

• Allows users to cancel immediate redirection to the provider and log in with local credentials.

Disable Auto-redirect to Application:

Enter the Service Desk portal URLs (separated by semicolons) for which Auto Redirect should be disabled. If left empty, auto-redirect will remain enabled for all portals.

Example

If you configure:

Auto-redirect will be disabled for these specific portal URLs, and users accessing them will not be directly redirected to the Identity Provider.

JSM-Specific Emergency Access Settings

This enables a separate login path (Emergency URL) that bypasses SSO for JSM.

• Ensures admins can regain access if SSO is misconfigured, unavailable, or the provider is down.

Important: Always document your emergency URL securely and restrict it to trusted administrators.

Enable AutoRedirect Delay JSM

Delays the redirect to the provider by showing a progress bar.

• Allows users to cancel immediate redirection to the provider and log in with local credentials.

Confluence-Specific Sign-In Settings

Anonymous Access

When disabled, users accessing Confluence public pages will be automatically redirected to the SSO provider for authentication.

Allow Guest Login

When enabled, users who do not have an existing account in Confluence will be allowed to access the application as guest users

Secure Admin Login

When enabled, administrators are required to re-authenticate via SSO even if already logged in.

• Requires a secondary confirmation before accessing admin/settings pages.

Why use it: Adds protection against session hijacking and unauthorised admin access.

Auto-Redirect To Provider From Admin Screen

When enabled, users attempting to access administrative functionalities will be automatically redirected to the SSO provider for re-authentication.

Home All Handbooks OAuth / OpenID SSO

Header-Based Redirection

Overview

Header-based redirection allows you to automatically send users to a specific provider based on HTTP headers present in the incoming request. It eliminates the need for manual provider selection by evaluating custom headers and directing users accordingly, ensuring a seamless and efficient authentication experience.

How It Works

• The specified header name must be present in the request. Header names are case-insensitive.
• The header value is evaluated using a regular expression.
• If the header value is left empty, the rule matches any value for that header.
• Rules are processed in a top-to-bottom order.
• The first matching rule determines which provider is used for redirection.
• If multiple headers with the same name exist in the request, only the first header value is evaluated.

Example: Multi-Company Jira Instance with Header-Based Redirection

If your application serves multiple organizations, each with its own identity provider (IdP), you can use header-based redirection to route users automatically. This is commonly implemented when requests pass through a reverse proxy, which adds custom headers based on the client network.

Configuration Scenario

Request Flow:

• A user from Alpha Corp accesses Jira through a reverse proxy.
• The proxy injects the header: X-Company: Alpha
• The plugin evaluates the configured rules sequentially.
• The rule matching X-Company = Alpha is identified.
• The user is redirected to the Alpha IdP for authentication.

This feature enables seamless, automatic routing of users to the correct IdP based on their originating network, without manual intervention.

Test Header Matching

This feature allows you to test configured header rules by providing a header name and value, and determining the provider to where the user will be redirected.

This feature allows administrators to validate header-based redirection rules before deploying them in production.

You can:

• Provide a header name and value
• Simulate rule evaluation
• Identify which IdP the request would be redirected to.

This helps ensure the correctness of regex patterns and rule ordering.

Home All Handbooks OAuth / OpenID SSO

Redirection Rules

The Redirection Rules section allows you to automatically redirect users to their respective configured Identity Provider (IdP) based on the user's domain, group, or directory. You can configure redirection rules for both the Jira and Jira Service Management apps.

Types Of Redirection:

The miniOrange’s OAuth/OIDC plugin supports three types of redirection methods:

1. Domain-Based Redirection

Description:

Domain-based redirection redirects users to the configured Identity Provider based on their email domain. Redirection is triggered when the domain equals the specified domain value or contains the defined domain string.

Use Case:

Ideal for organizations managing multiple email domains that require users to authenticate through a designated IdP automatically.

Example:

If a user logs in with user@company.com, they are redirected to the IdP configured for the company.com domain.

When to Use:

• Multi-domain organizations
• Companies supporting subsidiaries or partner domains
• Environments requiring domain-specific authentication

2. Group-Based Redirection

Description:

Group-based redirection redirects users according to the groups to which they are assigned in Jira. Redirection is triggered when the group name equals the specified group or when the group name contains the specified string value.

This method is particularly useful when different departments or teams rely on separate Identity Providers.

Use Case:

Recommended for enterprises where departments such as Finance, Engineering, or HR require different identity providers for authentication.

Example:

Users belonging to the Finance group can be redirected to one IdP, while members of the Engineering group are redirected to another.

When to Use:

• Department-level security requirements
• Organizations with varied authentication policies
• Role-based access strategies

3. Directory-Based Redirection

Description:

Directory-based redirection redirects users based on the directory they belong to. Redirection is triggered when the directory equals the specified directory or when the directory name contains the specified string value.

This is commonly used for external directories such as Microsoft Active Directory and LDAP, as well as newly created directories.

Use Case:

Best suited for organizations operating with multiple user directories or hybrid identity environments that require directory-specific authentication.

Example:

Users stored in a designated directory are automatically redirected to the IdP configured for that directory.

When to Use:

• Hybrid identity infrastructures
• Organizations with multiple user directories.
• Enterprises separating internal and external users

Default Rule:

Configure a default redirection rule to determine where users are directed if no other redirection rules match during login. You can choose to redirect users to the login page, a configured Identity Provider (IdP), or a specified URL.

Default Rule Options:

• Login Page: Redirect users to the application’s default login page.
• Configured IdP: Automatically redirect users to a selected, pre-configured Identity Provider.
• Redirect URL: Send users to a custom URL defined by the administrator.

Summary

Redirection Rules enhance both security and user experience by ensuring users authenticate through the correct Identity Provider automatically. By leveraging domain, group, and directory-based redirection, administrators can streamline access management while maintaining flexibility and organizational control within Jira and JSM.

Home All Handbooks OAuth / OpenID SSO

Session Management

The Session Management feature allows administrators to control how long users remain authenticated within the application.

When the Set Remember Me Cookie option is enabled, a persistent cookie is created that keeps users logged in across sessions. Users remain logged in even after closing and reopening their browser, until they manually log out.

Key Functionality

• Persistent Login: When enabled, the Remember Me cookie preserves the user’s authenticated session, allowing them to stay signed in even after closing and reopening the browser.
• Improved User Experience: Minimizes login interruptions, especially for users who frequently access the application.
• Administrator Control: Ensures sessions remain active only according to the configured behavior and terminate when the user logs out.

When to Use

• Organizations that want to provide a seamless and uninterrupted login experience.
• Environments where users access the platform regularly throughout the day.

Home All Handbooks OAuth / OpenID SSO

Look and Feel Configuration

Purpose

The Look and Feel section allows administrators to customize how the OAuth SSO login experience appears in the Atlassian instance.

This tab focuses only on UI behavior and presentation, without affecting authentication logic or provider selection.

Overview

Using the Look and Feel settings, you can:

• Customize the SSO login button text and placement
• Hide default Jira or Jira Service Management login forms
• Replace default login pages with custom SSO templates
• Control fallback access to default login pages
• Customize SSO error pages and messages

These settings help create a consistent and branded login experience for users accessing your Atlassian instance.

Key Features and Configuration Settings

Login Button Text

Customize the label of the SSO login button displayed on the login page.

• Applicable only when a single identity provider is configured
• When multiple providers are configured, provider names are shown automatically

Example:

Use OAuth Login

Login with Corporate Account

SSO Button Position

Controls where the SSO button appears on the login page.

• Before Login Button
• After Login Button

This setting affects only the visual placement and does not change login behavior.

Login Form Settings

Hide the Default Jira Login Form

• Enabled: Jira’s username and password fields are hidden. Only SSO login options are shown.
• Disabled: Jira’s default login form is displayed along with SSO options.

Hide the Default JSM Login Form

• Enabled: Jira Service Management login form is hidden and only SSO options are shown.
• Disabled: Default JSM login form remains visible.

Custom Login Template for Jira

Replace the default Jira login page with a custom-designed SSO login template.

• Supports HTML, CSS, and JavaScript customization
• Suitable for single OAuth/OIDC provider setups
• Administrators can fully control layout, messaging, and branding

The provided template is a default example and can be modified as needed.

Custom Login Template for Jira Service Management (Customer Portal)

Show Custom Login Template for Customer Portal

Replace the default JSM customer portal login page with a custom SSO login template.

• Applies only to customer-facing login pages
• Maintains compatibility with Jira Service Management navigation
• Supports custom messaging and branding

Default Login Page URLs (Fallback Access)

These URLs allow administrators or users to access default login pages when custom templates are enabled.

Default Jira Login Page URL

Use this URL to access Jira’s default login page.

Default Customer Portal Login Page URL

Use this URL to access the default Jira Service Management customer portal login page.

Code to Add a New SSO Button

Use the following snippet to add additional SSO buttons when multiple identity providers are configured:

Replace Provider ID with the actual provider ID from the configuration tab.

SSO Error Message Template

Redirect users to a custom error page if an SSO login attempt fails.

• Fully customizable HTML template
• Displays error codes and messages
• Can include help links or administrator contact information

This template controls only how errors are displayed, not how they are generated.

Custom Error Message Configuration

Configure custom messages for specific SSO failure scenarios:

• Invalid Client
• User Creation Disabled
• User Not Allowed
• User Is Deactivated

Example Error Code

INVALID_CLIENT

Occurs when SSO fails due to invalid or incorrect client credentials configured for the identity provider.

Summary

The Look and Feel tab helps tailor the visual and user-facing aspects of OAuth SSO in your Atlassian instance.

It enables branding, UI customization, and clear error messaging while keeping authentication logic and provider behavior unchanged.

Home All Handbooks OAuth / OpenID SSO

Post Logout Configuration

The Post Logout Configuration section allows you to control what users see and where they are redirected after logging out from the Atlassian application.

Overview

When a user logs out from the Atlassian application, their application session is terminated.

After logout, the user can either be redirected to a custom URL or shown a custom logout page.

The Post Logout tab lets you define this post-logout behavior within the OAuth/OIDC provider.

Key Features and Configuration Settings

Custom Logout URL

This option defines the URL where users are redirected after logging out from the Atlassian application.

Enabled (URL configured):

• Users are redirected to the specified URL after logout.
• The URL can be internal or external.

Disabled (left empty):

• Users are redirected to the default Atlassian login page.

Use case: Redirect users to a company portal or a logout confirmation page.

Custom Logout Template for Atlassian

This option allows you to display a custom page after logout instead of performing an automatic redirect.

Enabled:

• A custom HTML-based logout page is shown to the user.
• Useful for displaying logout confirmation messages or guidance.
• Supports the $baseUrl variable for referencing the Atlassian application URL.

Disabled:

• Users follow the standard logout redirect behavior.

Use case: Display a branded logout message or provide a manual login link.

Summary

The Post Logout Configuration controls how users are handled after logging out from the Atlassian application. It allows you to define post-logout redirection and customize the logout experience within the OAuth/OIDC provider, ensuring a clear and predictable exit flow for users.

Home All Handbooks OAuth / OpenID SSO

Global SSO Settings

The Global SSO Settings section centralizes controls that affect how Single Sign-On (SSO) behaves across your Atlassian application. These settings determine where SSO is enabled, whether end users can perform certain actions (like resetting passwords), security boundaries for application APIs, and automatic account activation behavior.

Enable SSO for Jira Software / Confluence

• When this option is enabled, users will be able to authenticate into Jira Software / Confluence using the configured OAuth/OpenID Provider.
• If disabled, users will continue to authenticate using native login unless overridden by other settings.

Enable SSO for Jira Service Management

This option enables SSO for Jira Service Management, allowing both service desk agents and customers to sign in via SSO.

Restrict Access to Plugin APIs

When enabled, the plugin’s internal APIs are restricted to requests originating from the same Atlassian instance. This prevents external clients (for example, Postman, curl, or remote sessions) from accessing plugin APIs.

Important

• If your instance is deployed behind a reverse proxy, review your Referrer Policy configuration.
• When the web server or proxy is configured to suppress or modify the Referer header, the Restrict Access to Plugin APIs feature may not function as expected. In such cases, this option should be disabled to avoid unintended SSO or API access issues.

Allow Users to Change Password

This setting determines whether end users can use the application’s built-in password management features, such as Change Password and Forgot Password.

• Enabled: Users can reset or update their local application passwords on their own.
• Disabled: Only system administrators can modify or reset user passwords.

Auto Activate Users on SSO

When enabled, users who are currently deactivated in the application will be automatically activated if they successfully authenticate via SSO.

This setting simplifies user management when onboarding large teams, but should be used with caution if deactivated users should remain blocked for compliance reasons.

Automatically Login Users

When enabled, users who already have an active session with the Provider will be logged in automatically without being prompted to authenticate again.

Callback URL

{baseurl}/plugins/servlet/oauth/autocallback

Configure this callback URL in your OAuth provider under the Redirect URIs.

Force Re-Authentication

When enabled, users must re-authenticate at the Provider even if an active session already exists on the provider side.

Home All Handbooks OAuth / OpenID SSO

Backup and Restore

The Backup and Restore tab in the miniOrange OAuth/OIDC plugin allows administrators to back up and restore their configuration by downloading and uploading configuration files.

This feature is particularly useful during environment migrations, disaster recovery, or when replicating configurations from a test environment to production within Atlassian applications.

Configuration Backup and Restore Methods:

The plugin provides the following methods to back up and restore configurations:

• Download/Upload App Configuration via File
• Download/Upload App Configuration via REST API

Download/Upload App Configurations via File

Download App Configuration File

Use the Download Configuration button to export your current plugin configuration settings. This file acts as a backup and can be reused to replicate configurations in another environment.

Upload App Configuration File

Use the Import Configuration option to upload a previously downloaded configuration file and restore the settings instantly.

Recommendation: Always maintain a recent backup before making significant configuration changes.

Download/Upload App Configurations via REST API

Fetch Plugin Configuration via REST API

Use the following endpoint to retrieve the current configuration in JSON format:

Endpoint Details:

URL: https://<base-url>/plugins/servlet/oauth/configureplugin

Replace <base-url> with your Jira instance URL.

• Method: GET

Request Parameters

Headers:

• Content-Type: application/json
• Authorization: Basic <base64 encoded admin_username:password>

When executed successfully, this request returns the complete plugin configuration in raw JSON format.

Upload App Configuration File via REST API

Use the following endpoint to upload and restore the plugin configuration in JSON format:

Endpoint Details:

URL: https://<base-url>/plugins/servlet/oauth/configureplugin

Replace <base-url> with your Jira instance URL.

• Method: POST

Request Parameters

Headers:

• Content-Type: application/json
• Authorization: Basic <base64 encoded admin_username:password>

Body:

• Select Raw format.
• Set content type to application/json.
• Paste the JSON configuration data obtained from the GET request response or the downloaded app configuration file.

After pasting the JSON data, execute the request. The plugin configuration will be uploaded successfully.

Home All Handbooks OAuth / OpenID SSO

Troubleshooting

The Troubleshooting tab provides steps to download the necessary information, such as application log files, to help troubleshoot issues.

Overview

When an issue occurs, the plugin allows you to capture logs that help identify errors, misconfigurations, or unexpected behavior during the login process.

These logs are mainly used to analyze authentication and connectivity issues.

Key Features and Configuration Settings

Log File

Use this option to capture detailed logs generated by the OAuth plugin.

Steps to enable and collect logs:

• Go to Administration → Logging and Profiling
• Under Default Loggers, click Configure
• Enter com.miniorange.oauth in the package name field
• Select DEBUG as the logging level and click Add
• Open an Incognito / Private browser window and reproduce the issue
• Download the Server logs using the Download button

These logs capture detailed plugin execution details required for troubleshooting.

Network Log File

Use this option to capture browser network logs.

Steps to capture browser network logs:

• Open the browser in Incognito / Private mode
• Open Developer Tools
  • Chrome / Edge: F12 or Ctrl + Shift + I
• Go to the Network tab
• Enable Preserve log
• Clear existing network entries
• Reproduce the issue (initiate the login flow)
• Use the Export option in the Network tab
• Export the logs as a HAR file with content
• Save the downloaded .har file

These network logs capture HTTP requests and responses exchanged during the login flow and help identify redirect, token, or connectivity issues.

Summary

The Troubleshooting section helps you collect essential diagnostic information from your Atlassian instance. By capturing plugin logs and browser network logs, issues can be identified and resolved more efficiently.