StarKnowledge.OAuth.Maui.Atlassian 1.0.3

Azure & Okta Atlassian MAUI Package

A ready-to-use .NET MAUI NuGet package for OAuth 2.0 authentication. Easily integrate Atlassian, Azure AD, Okta, or any OAuth 2.0 provider into your MAUI applications with just a few lines of code.

🚀 Quick Start

Step 1: Install the Package

Add the package to your MAUI project:

Using Package Manager:

Install-Package StarKnowledge.OAuth.Maui.Atlassian

Using .NET CLI:

dotnet add package StarKnowledge.OAuth.Maui.Atlassian

Or add to your .csproj file:

<PackageReference Include="StarKnowledge.OAuth.Maui.Atlassian" Version="1.0.0" />

Step 2: Configure Your App

Open your MauiProgram.cs file and add the following:

using AzureAdAtlassianConnectApp.Services;
using AzureAdWithAtlassian.Xamarin.Essentials;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder.UseMauiApp<App>();

        // Step 1: Create secure storage instance
        var secureStorages = new SecureStorageWrapper();
        builder.Services.AddSingleton<ISecureStorages>(secureStorages);

        // Step 2: Configure your OAuth provider settings
        ConfigureOAuthProvider(secureStorages);

        // Step 3: Register the authentication service
        builder.Services.AddSingleton<HttpClient>(new HttpClient());
        builder.Services.AddSingleton<IAtlassinAccessToken>(sp =>
        {
            var secureStorage = sp.GetRequiredService<ISecureStorages>();
            var client = sp.GetRequiredService<HttpClient>();
            return new AtlassinAccessToken(secureStorage, client);
        });

        return builder.Build();
    }

    private static void ConfigureOAuthProvider(ISecureStorages secureStorages)
    {
        // Replace these with your actual OAuth provider settings
        secureStorages.SetAsync("CallbackUrl", "yourapp://oauth2redirect/callback").GetAwaiter().GetResult();
        secureStorages.SetAsync("AuthorizeEndPoint", "https://auth.atlassian.com/authorize").GetAwaiter().GetResult();
        secureStorages.SetAsync("TokenEndpoint", "https://auth.atlassian.com/oauth/token").GetAwaiter().GetResult();
        secureStorages.SetAsync("AtlassianConnectApp_ClientId", "YOUR_CLIENT_ID").GetAwaiter().GetResult();
        secureStorages.SetAsync("AtlassianConnectApp_ClientSecret", "YOUR_CLIENT_SECRET").GetAwaiter().GetResult();
        secureStorages.SetAsync("Scopes", "read:jira-work write:jira-work").GetAwaiter().GetResult();
    }
}

Step 3: Use in Your Code

In any page or view model, inject and use the service:

using AzureAdAtlassianConnectApp.Services;

public partial class LoginPage : ContentPage
{
    private readonly IAtlassinAccessToken _authService;

    public LoginPage(IAtlassinAccessToken authService)
    {
        InitializeComponent();
        _authService = authService;
    }

    private async void LoginButton_Clicked(object sender, EventArgs e)
    {
        try
        {
            // This opens the OAuth provider's login page
            var result = await _authService.GetAtlassianAccessToken();
            
            if (result.Contains("access_token:"))
            {
                // Extract the access token
                var accessToken = result.Replace("access_token: ", "");
                
                // Use the token for your API calls
                await DisplayAlert("Success", "Logged in successfully!", "OK");
            }
            else
            {
                await DisplayAlert("Error", result, "OK");
            }
        }
        catch (Exception ex)
        {
            await DisplayAlert("Error", ex.Message, "OK");
        }
    }
}

Step 4: Configure iOS (Required for iOS apps)

Add this to your Platforms/iOS/Info.plist file:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>  
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>yourapp</string>  
    <string>https</string>    
    <string>http</string>     
</array>

Important: Replace yourapp with your actual app's URL scheme (the part before :// in your CallbackUrl).

Configuration Details

Mandatory Requirements:

• CFBundleURLTypes - Essential for registering your app's custom URL scheme with iOS
• Your custom URL scheme (e.g., scanstar, myapp) - Required for OAuth provider to redirect back to your app after authentication
• yourapp in LSApplicationQueriesSchemes - Required so iOS knows your app can handle the callback URL

Recommended Configuration:

• https - Strongly recommended because:
  • All modern OAuth 2.0 providers (Atlassian, Azure AD, Okta) use HTTPS endpoints
  • Allows iOS to properly route HTTPS requests
  • Required for secure authentication flows
  • Without it, OAuth provider communication may fail silently

Optional Configuration:

• http - Only needed if:
  • Using legacy OAuth providers with non-HTTPS endpoints
  • Testing in development environments with HTTP servers
  • Can be safely omitted for production apps using standard OAuth providers

Minimal Configuration (Bare Minimum):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>yourapp</string>
    <string>https</string>
</array>

⚠️ Recommendation: Use the full configuration above (with all three schemes) to ensure compatibility with all OAuth providers and avoid potential runtime issues.

Step 5: Configure Android (Required for Android apps)

1. Platforms/Android/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
	<application android:allowBackup="true" android:icon="@mipmap/appicon" android:roundIcon="@mipmap/appicon_round" android:supportsRtl="true">
		
		<activity android:name=".WebAuthenticationCallbackActivity" />
	</application>
	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
	<uses-permission android:name="android.permission.INTERNET" />
	<queries>
		
		<intent>
			<action android:name="android.intent.action.VIEW" />
			<category android:name="android.intent.category.BROWSABLE" />
			<data android:scheme="https" />
		</intent>
		
		<intent>
			<action android:name="android.support.customtabs.action.CustomTabsService" />
		</intent>
	</queries>
</manifest>

2. Platforms/Android/WebAuthenticationCallbackActivity.cs

using Android.App;
using Android.Content;
using Android.Content.PM;

namespace YourApp.Platforms.Android
{
    [Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
    [IntentFilter(
        new[] { Intent.ActionView },
        Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
        DataScheme = "myapp")]
    public class WebAuthenticationCallbackActivity : WebAuthenticatorCallbackActivity
    {
    }
}

Important: Replace yourapp with your actual app's URL scheme (the part before :// in your CallbackUrl).

Configuration Details

Mandatory Requirements:

• WebAuthenticationCallbackActivity - Essential for handling OAuth callback redirects on Android
  • Inherits from WebAuthenticatorCallbackActivity (built-in MAUI class)
  • No need to implement OnResume() manually - handled by base class
• [IntentFilter] attribute - Must specify your custom URL scheme (e.g., yourapp)
  • DataScheme must match your CallbackUrl scheme
  • Exported = true - Required to allow external apps to start this activity
• Permissions - Required for OAuth communication:
  • android.permission.INTERNET - Mandatory for HTTP/HTTPS requests
  • android.permission.ACCESS_NETWORK_STATE - For checking network connectivity

Recommended Configuration:

• <queries> section in AndroidManifest.xml - Recommended because:
  • Allows your app to query if HTTPS scheme is available
  • Ensures proper communication with OAuth provider servers
  • Required for Android 11+ (API 30+) to access external URLs
  • CustomTabsService - Enables Chrome Custom Tabs for secure authentication
  • Without it, OAuth provider communication may fail on newer Android versions

Minimal Configuration (Bare Minimum):

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(
    new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.Category.BROWSABLE },
    DataScheme = "yourapp")]
public class WebAuthenticationCallbackActivity : WebAuthenticatorCallbackActivity
{
}

⚠️ Recommendation: Use the full configuration above (with the <queries> section and all permissions) to ensure compatibility with all Android versions and OAuth providers, especially Android 11+.

Step 6: Register Callback URL in Your OAuth Provider

Go to your OAuth provider's developer console and register:

Callback URL: yourapp://oauth2redirect/callback

This must match exactly what you set in CallbackUrl in Step 2.

📋 Configuration Examples

For Atlassian

secureStorages.SetAsync("CallbackUrl", "yourapp://oauth2redirect/callback").GetAwaiter().GetResult();
secureStorages.SetAsync("AuthorizeEndPoint", "https://auth.atlassian.com/authorize").GetAwaiter().GetResult();
secureStorages.SetAsync("TokenEndpoint", "https://auth.atlassian.com/oauth/token").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientId", "YOUR_ATLASSIAN_CLIENT_ID").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientSecret", "YOUR_ATLASSIAN_CLIENT_SECRET").GetAwaiter().GetResult();
secureStorages.SetAsync("Scopes", "read:jira-work write:jira-work read:jira-user").GetAwaiter().GetResult();

Get your credentials from: https://developer.atlassian.com/console/myapps/

For Azure AD / Microsoft Entra ID

secureStorages.SetAsync("CallbackUrl", "yourapp://oauth2redirect/callback").GetAwaiter().GetResult();
secureStorages.SetAsync("AuthorizeEndPoint", "https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize").GetAwaiter().GetResult();
secureStorages.SetAsync("TokenEndpoint", "https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientId", "YOUR_AZURE_CLIENT_ID").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientSecret", "YOUR_AZURE_CLIENT_SECRET").GetAwaiter().GetResult();
secureStorages.SetAsync("Scopes", "User.Read offline_access").GetAwaiter().GetResult();

Get your credentials from: Azure Portal → App Registrations

For Okta

secureStorages.SetAsync("CallbackUrl", "yourapp://oauth2redirect/callback").GetAwaiter().GetResult();
secureStorages.SetAsync("AuthorizeEndPoint", "https://your-company.okta.com/oauth2/default/v1/authorize").GetAwaiter().GetResult();
secureStorages.SetAsync("TokenEndpoint", "https://your-company.okta.com/oauth2/default/v1/token").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientId", "YOUR_OKTA_CLIENT_ID").GetAwaiter().GetResult();
secureStorages.SetAsync("AtlassianConnectApp_ClientSecret", "YOUR_OKTA_CLIENT_SECRET").GetAwaiter().GetResult();
secureStorages.SetAsync("Scopes", "openid profile email").GetAwaiter().GetResult();

Get your credentials from: Okta Admin Console → Applications

🔧 What You Need to Provide

1. OAuth Provider Credentials

You'll need to get these from your OAuth provider:

• Client ID - Your application's client identifier
• Client Secret - Your application's secret key
• Authorization Endpoint - The URL where users log in
• Token Endpoint - The URL to exchange authorization code for token
• Scopes - Permissions your app needs (space-separated)

2. Custom URL Scheme

Choose a unique URL scheme for your app (e.g., myapp, yourapp, scanstar). This will be used in:

• Your callback URL: {scheme}://oauth2redirect/callback
• iOS Info.plist configuration
• OAuth provider redirect URI registration

3. OAuth Provider Setup

Register your callback URL in your OAuth provider's developer console:

• Redirect URI: {your-scheme}://oauth2redirect/callback

✅ What the Package Handles for You

• ✅ Opens OAuth provider's login page
• ✅ Handles user authentication flow
• ✅ Receives callback from OAuth provider
• ✅ Exchanges authorization code for access token
• ✅ Returns access token ready to use
• ✅ Works on iOS, Android, and Mac Catalyst
• ✅ Uses secure native authentication on iOS (ASWebAuthenticationSession)
• ✅ Uses secure authentication on Android (WebAuthenticator)

📱 Platform Support

• iOS 12.0+ (uses native ASWebAuthenticationSession)
• Android API 21+ (uses MAUI WebAuthenticator)
• Mac Catalyst 15.0+

🎯 Complete Example

Here's a complete working example summary:

For detailed configuration and code examples, refer to:

• Step 2 - Complete MauiProgram.cs setup
• Step 3 - Complete MainPage.xaml.cs usage
• Step 4 - Complete iOS Info.plist configuration
• Step 5 - Complete Android manifest and activity setup

All code examples are provided in the respective configuration steps above. The complete example demonstrates how these components work together in a real MAUI application.

❓ Troubleshooting

"Callback URL is invalid" Error

Solution:

1. Check that your callback URL in code matches exactly what's registered in your OAuth provider
2. Verify the URL scheme in Info.plist matches your callback URL scheme
3. Ensure there are no trailing spaces or extra characters

iOS: App doesn't open after authentication

Solution:

1. Verify URL scheme is registered in Info.plist
2. Test manually: Open Safari and type {your-scheme}://oauth2redirect/callback
3. If app opens, the scheme is correct - check OAuth provider configuration

"Invalid Client" Error

Solution:

1. Double-check your Client ID and Client Secret
2. Verify they're from the correct OAuth app
3. Ensure the app is active in your OAuth provider

Android: Authentication doesn't work

Solution:

1. Ensure WebAuthenticationCallbackActivity exists in Platforms/Android/
2. Check AndroidManifest.xml has proper intent filters
3. Verify callback URL matches registered scheme

📚 Additional Information

How It Works

1. User clicks "Login" button
2. Package opens OAuth provider's login page
3. User enters credentials and authorizes
4. OAuth provider redirects to your app with authorization code
5. Package automatically exchanges code for access token
6. You receive the access token ready to use

Security

• All credentials stored securely using MAUI SecureStorage
• iOS uses native ASWebAuthenticationSession (most secure)
• Android uses MAUI WebAuthenticator with secure storage
• No credentials stored in code or configuration files

Customization

The package uses standard OAuth 2.0, so you can:

• Use any OAuth 2.0 provider
• Customize scopes based on your needs
• Use different callback URLs for different environments

📞 Support

For issues or questions:

• Check the troubleshooting section above
• Review your OAuth provider's documentation
• Verify all configuration values are correct

📄 License

Copyright © Star-knowledge. All rights reserved.

Package Version: 1.0.2
Last Updated: March 2026