Authentication

GeoBlazor Authentication

All GeoBlazor users must register at licensing.dymaptic.com to obtain a license key. This is free for the open-source GeoBlazor Core library, but is still a requirement for running the application. This helps dymaptic track usage, keep you informed of new releases and features, and be aware of any issues that arise. We do not sell or share your information with any third parties, and you can unsubscribe from emails at any time.

When you register, you will generate a license key that you can use in your application. This key is stored in the appsettings.json file, the user secret secrets.json file, or an environment-specific file like appsettings.Development.json or appsettings.Production.json. Be aware that WebAssembly projects do not support user secrets, and do not by default see appsettings files in the root folder, so you need to place the files inside the wwwroot folder for them to be accessible by the client application. Learn more about configuration files in .NET

Note: Older versions of the documentation referenced “RegistrationKey” instead of “LicenseKey” for GeoBlazor Core. We have made the two terms interchangeable, so you can use either in your configuration files.

{
    "GeoBlazor" : {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

ArcGIS Authentication

GeoBlazor utilizes the ArcGIS JavaScript API for map rendering, Geospatial calculations, and to supply map tile data. Therefore, every GeoBlazor application must authenticate with ArcGIS in some way. To get started, read ArcGIS Accounts and Tokens to understand the different types of accounts and tokens available, and to create your first tokens or applications. Once you have an API Key or OAuth Application created in ArcGIS, return here to learn how to configure your GeoBlazor application to use it.

API Key

Once you have an API key, add a single line to the configuration file where you store your GeoBlazor license key. You may also set the API key using the AuthenticationManager class.

{
    "ArcGISApiKey": "your-ArcGIS-api-key",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

User Authentication

Find the ClientId from your Portal Item page after creating your OAuth 2 Application, and add it to the configuration file where you store your GeoBlazor license key as ArcGISAppId.

{
    "ArcGISAppId": "your-ArcGIS-app-client-id",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

If you are using an ArcGIS Enterprise portal, you will also need to add the ArcGISPortalUrl to your configuration.

{
    "ArcGISAppId": "your-ArcGIS-app-client-id",
    "ArcGISPortalUrl": "https://arcgis.yourcompany.com",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

Users will be prompted to log in automatically on the first map load if you add PromptForOAuthLogin="true" to your MapView.

<MapView PromptForOAuthLogin="true">
    <Map>
        <Basemap>
            <BasemapStyle Name="BasemapStyleName.ArcgisLightGray" />
        </Basemap>
    </Map>
</MapView>

Or you can call the AuthenticationManager.Login() method at any time to trigger the login prompt.

await authenticationManager.Login();

Once the user logs in, the authentication token will be stored for the duration of the user’s browser session. You can also retrieve the current authentication token using the AuthenticationManager class.

App Authentication

Because GeoBlazor can run in the browser using WebAssembly, we cannot fully implement the OAuth 2.0 App Authentication token refresh for your application. This must always be done on the server side. App Authentication Token Refresh provides instructions for setting up your ASP.NET Core server application to refresh App tokens. Once you have this logic configured, you can use the AuthenticationManager class to register the returned tokens.

The configuration setup is similar to User Authentication. Find the ClientId from your Portal Item page after creating your OAuth 2 Application, and add it to the configuration file where you store your GeoBlazor license key as ArcGISAppId.

{
    "ArcGISAppId": "your-ArcGIS-app-client-id",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

If you are using an ArcGIS Enterprise portal, you will also need to add the ArcGISPortalUrl to your configuration.

{
    "ArcGISAppId": "your-ArcGIS-app-client-id",
    "ArcGISPortalUrl": "https://arcgis.yourcompany.com",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

Authentication Manager Class

The AuthenticationManager is a DI-injected class that handles runtime authentication actions for GeoBlazor. It is responsible for both the Api Key and OAuth authentication methods. It also allows you to retrieve the current authentication token with GetCurrentToken regardless of how that token was generated.

Custom Token Injection

If you don’t want to store your API key in the typical IConfiguration settings, you can set the value directly in AuthenticationManager

// set the API key to the value you loaded from your secure store
authenticationManager.ApiKey = "yourKeyValue";
// then call
await authenticationManager.Initialize();

Once the token is initialized, it will be picked up automatically by every MapView, SceneView, and logic component. You can also set AppId and PortalUrl directly in `AuthenticationManager for OAuth flows.

Fonts Url

The AuthenticationManager also has a FontsUrl property that you can set to a custom URL for the ArcGIS fonts. This is useful if you are running an ArcGIS Enterprise portal that is disconnected from the public internet.

AuthenticationManager.FontsUrl = $"{portalUrl}/apps/fonts";

Authentication Methods

The AuthenticationManager class provides several methods for authentication:

• Login() - Prompts the user to log in using OAuth.
• IsLoggedIn() - Checks if the user is currently logged in with a valid token.
• EnsureLoggedIn() - Ensures that the user is logged in, prompting for login if necessary.
• RegisterToken(string token, DateTimeOffset expires) - Registers a token that you have retrieved from your server or another source.
• GetCurrentToken() - Retrieves the current authentication token, regardless of how it was set.

Allow Default Esri Login

By default, GeoBlazor prevents you from loading a map without a token. However, Esri has built in a simple in-map popup login that you can use. This is not as secure as an OAuth login, but it is relatively straightforward.

To allow default logins, do one of the following.

In appsettings.json:

{
    "AllowDefaultEsriLogin": true
}

or

When defining your MapView or SceneView:

<MapView AllowDefaultEsriLogin="true">
    <Map></Map>
</MapView>

Prevent API Token Prompt

This is essentially another way to silence the API token check in GeoBlazor. Calling ArcGIS resources will still show the default login same as AllowDefaultEsriLogin above.

To silence the api key prompt, do one of the following.

In appsettings.json:

{
    "PromptForArcGISKey": false
}

or

When defining your MapView or SceneView:

<MapView PromptForArcGISKey="false">
    <Map></Map>
</MapView>