OpenID Connect Provider Manager (.NET)

Relativity supports OpenID Connect (OIDC) providers for authenticating to a Relativity instance during login. You can set scopes, claims, and other properties on an OIDC provider through the UI and the OIDC Provider Manager API. For more information, see Authentication on the RelativityOne documentation site.

The OIDC Provider Manager API provides the following functionality for programmatically working with providers:

  • CRUD operations on OIDC providers.
  • CRUD operations on group claim mappings.
  • CRUD operations on required claims.

Sample use cases for this API include the following:

  • Updating the trusted IPs on an OIDC provider.
  • Creating a new OIDC provider used for users who are added during Just-In-time provisioning.
  • Adding one or more required claims that a user must have to log in successfully.

You can also use the OIDC Provider Manager API through REST. For more information, see OpenID Connect Provider Manager (REST).

The Relativity.Identity.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for the OIDC Provider API

Review the following information to learn about the methods and classes used by the OIDC Provider Manager API.

The OIDC Provider API includes the following methods available on the IOpenIDConnectProviderManager interface in the Relativity.Identity.<VersionNumber>.Services namespace:

Note: The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.

OIDC provider methods

Group claim mappings methods

Required claims methods

The OIDC Provider API uses the following classes and enumerations:

  • GroupClaimMapping class - represents a mapping between a claim value and a specific group during Just-In-Time provisioning.
  • JITSettings class - represents Just-In-Time settings on an OIDC provider.
  • OpenIDConnectProvider class - represents an OIDC external identity provider.
  • OpenIDConnectProviderResponse class - represents a response for an operation on an OIDC external identity.
  • RequiredClaim class - represents a required claim necessary for a user to be created during Just-In-Time provisioning.
  • ResponseType enumeration - includes the following values: Code, IDToken, and Token.

Create an OIDC provider

Use the CreateAsync() method to create a new OIDC provider. This method takes a OpenIDConnectProvider object as an argument and returns a OpenIDConnectProviderResponse object.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    var provider = new OpenIDConnectProvider()
    {
        Name = "OIDC Auth Provider 3",
        Description = "Description",
        IsEnabled = true,
        SiteUri = new Uri("https://relativity.com/Relativity"),
        DisplayOnLoginPage = true,
        Caption = "OIDC Provider 1",
        ClientID = "1ba9d293-fde9-4501-9b12-b2c4234234324",
        ClientSecret = "secret",
        Authority = new Uri("https://login.microsoftonline.com/8afe73f9-0d93-4821-a898-c5c2dc320953/"),
        Flow = OAuth2Flow.Code,
        SubjectClaimType = "email",
        OpenIdScopes = new List<string> { "openid", "email", "profile" },
        JITSettings = new JITSettings()
        {
            Enabled = true,
            PersonalGroup = false,
            FirstNameClaimType = "firstnameclaim",
            LastNameClaimType = "lastnameclaim",
            EmailClaimType = "emailclaim",
            PersonalGroupClaimType = "personalgroupclaim",
            GroupClaimType = "groupclaim",
            Client = new DisplayableObjectIdentifier()
            {
                ArtifactID = 1015644
            }
        },
        TrustedIPs = "fe80::c20:8e40:319f:b84d%22\r\nlocalhost"
 
    };
 
    await manager.CreateAsync(provider);
}

Retrieve an OIDC provider

Use the ReadAsync() method to retrieve an OIDC provider. This method takes the Artifact ID of an OIDC provider and returns an OpenIDConnectProviderResponse object.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{          
    OpenIDConnectProviderResponse provider = await manager.ReadAsync(1020035);             
}

Update an OIDC provider

Use the UpdateAsync() method to modify an OIDC provider. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • An updated OpenIDConnectProvider object
Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    OpenIDConnectProviderResponse provider = await manager.ReadAsync(1020035);
 
    var updatedProvider = new OpenIDConnectProvider()
    {
        Name = provider.Name,
        Description = "Updated Description",
        IsEnabled = provider.IsEnabled,
        SiteUri = provider.SiteUri,
        DisplayOnLoginPage = provider.DisplayOnLoginPage,
        Caption = provider.Caption,
        ClientID = provider.ClientID,
        ClientSecret = provider.ClientSecret,
        Authority = provider.Authority,
        Flow = provider.Flow,
        SubjectClaimType = provider.SubjectClaimType,
        OpenIdScopes = new List<string> { "openid", "email", "profile", "scope1", "scope2" },
        JITSettings = new JITSettings()
        {
            Enabled = provider.JITSettings.Enabled,
            PersonalGroup = provider.JITSettings.PersonalGroup,
            FirstNameClaimType = "firstnameclaimupdated",
            LastNameClaimType = provider.JITSettings.LastNameClaimType,
            EmailClaimType = provider.JITSettings.EmailClaimType,
            PersonalGroupClaimType = provider.JITSettings.PersonalGroupClaimType,
            GroupClaimType = provider.JITSettings.GroupClaimType,
            Client = new DisplayableObjectIdentifier()
            {
                ArtifactID = 1015644
            }
        },
        TrustedIPs = "fe80::c20:8e40:319f:b84d%22\r\nlocalhost\r\n1.2.3.4"
 
    };
    await manager.UpdateAsync(1020035, updatedProvider);
}

Delete an OIDC provider

Use the DeleteAsync() method to remove an OIDC provider from Relativity. This method takes the Artifact ID of an OIDC provider.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    await manager.DeleteAsync(1020035);            
}

Create multiple group claim mappings for a provider

Use the MassCreateGroupClaimMappingsAsync() method to create multiple group claim mappings for an OIDC provider. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • A list of GroupClaimMapping objects

It returns a list of RelativityObjects.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    var mappings = new List<GroupClaimMapping>()
    {
        new GroupClaimMapping()
        {
            Group = new Securable<DisplayableObjectIdentifier>()
            {
                Secured = false,
                Value = new DisplayableObjectIdentifier()
                {
                    ArtifactID = 1023454,
                    Name = "First Level Group"
                }
            },
            ClaimValue = "FirstLevelClaim",
        },
        new GroupClaimMapping()
        {
            Group = new Securable<DisplayableObjectIdentifier>()
            {
                Secured = false,
                Value = new DisplayableObjectIdentifier()
                {
                    ArtifactID = 1023455,
                    Name = "Second Level Group"
                }
            },
            ClaimValue = "SecondLevelClaim",
        }
    };
 
    await manager.MassCreateGroupClaimMappingsAsync(1020035, mappings);
}

Retrieve all group claim mappings for a provider

Use the ReadAllGroupClaimMappingsAsync() method to retrieve all group claim mappings for an OIDC provider. This method takes the Artifact ID of an OIDC provider, and it returns a list of GroupClaimMapping objects.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    IEnumerable<GroupClaimMapping> providerGroupClaimMappings = await manager.ReadAllGroupClaimMappingsAsync(1020035);
}

Retrieve a group claim mapping

Use the ReadGroupClaimMappingAsync() method to retrieve a group claim mapping. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a GroupClaimMapping object

It returns a GroupClaimMapping object.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    GroupClaimMapping groupClaimMapping = await manager.ReadGroupClaimMappingAsync(1020035, 1025555);
}

Update a group claim mapping

Use the UpdateGroupClaimMappingAsync() method to update a group claim mapping. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a GroupClaimMapping object
  • An updated GroupClaimMapping object
Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    GroupClaimMapping groupClaimMapping = await manager.ReadGroupClaimMappingAsync(1020035, 1025555);
    groupClaimMapping.ClaimValue = "UpdatedClaimValue";
    await manager.UpdateGroupClaimMappingAsync(1020035, 1025555, groupClaimMapping);
}

Delete a group claim mapping

Use the DeleteGroupClaimMappingAsync() method to delete a group claim mapping. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a GroupClaimMapping object
Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    await manager.DeleteGroupClaimMappingAsync(1020035, 1025555);
}

Create multiple required claims for a provider

Use the MassCreateRequiredClaimsAsync() method to create multiple required claims for an OIDC provider. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • A list of RequiredClaim objects

It returns a list of RelativityObjects.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    var requiredClaims= new List<RequiredClaim>()
    {
        new RequiredClaim()
        {
            ClaimType = "claimType1",
            ClaimValue = "claimValue1"
        },
        new RequiredClaim()
        {
            ClaimType = "claimType2",
            ClaimValue = "claimValue2"
        }
    };
 
    await manager.MassCreateRequiredClaimsAsync(1020035, requiredClaims);
}

Retrieve all required claims for a provider

Use the ReadAllRequiredClaimsAsync() method to retrieve all required claims for an OIDC provider. This method takes the Artifact ID of an OIDC provider, and it returns a list of RequiredClaim objects.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    IEnumerable<RequiredClaim> providerRequiredClaims = await manager.ReadAllRequiredClaimsAsync(1020035);
}

Retrieve a required claim for a provider

Use the ReadRequiredClaimAsync() method to retrieve a required claim. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a RequiredClaim object

It returns a RequiredClaim object.

Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    RequiredClaim claim = await manager.ReadRequiredClaimAsync(1020035, 1025555);
}

Update required claim

Use the UpdateRequiredClaimAsync() method to modify a required claim. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a RequiredClaim object
  • An updated RequiredClaim object
Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    RequiredClaim claim = await manager.ReadRequiredClaimAsync(1020035, 1025555);
    claim.ClaimValue = "UpdatedClaimValue";
    claim.ClaimType = "UpdatedClaimType";
    await manager.UpdateRequiredClaimAsync(1020035, 1025555, claim);
}

Delete required claim

Use the DeleteRequiredClaimAsync() method to remove a required claim from Relativity. This method takes the following arguments:

  • Artifact ID of an OIDC provider
  • Artifact ID of a RequiredClaim object
Copy 
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
    await manager.DeleteRequiredClaimAsync(1020035, 1025555);
}