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).
Fundamentals for the OIDC Provider API
Review the following information to learn about the methods and classes used by the OIDC Provider Manager API.
Methods
The OIDC Provider API includes the following methods available on the IOpenIDConnectProviderManager interface in the Relativity.Identity.<VersionNumber>.Services namespace:
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
Classes and enumerations
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.
View code sample
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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.
View code sample
Copy
1
2
3
4
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
View code sample
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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.
View code sample
Copy
1
2
3
4
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.
View code sample
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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.
View code sample
Copy
1
2
3
4
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.
View code sample
Copy
1
2
3
4
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
View code sample
Copy
1
2
3
4
5
6
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
View code sample
Copy
1
2
3
4
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.
View code sample
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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.
View code sample
Copy
1
2
3
4
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.
View code sample
Copy
1
2
3
4
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
View code sample
Copy
1
2
3
4
5
6
7
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
View code sample
Copy
1
2
3
4
using (var manager = _factory.CreateProxy<IOpenIDConnectProviderManager>())
{
await manager.DeleteRequiredClaimAsync(1020035, 1025555);
}
