Organisation ID Client

Overview

The Freja eID Organisation ID Service allows you to set a specific, organisation-related identifier to any user. The end user must have previously downloaded the Freja eID mobile application, and registered an account in Freja eID, allowing you to refer to them through the use of one or more usernames.

The Organisation ID Service is available to end users whose identity has been validated with an ID document or the ones that have achieved the status of Freja eID Plus (users who, in addition to adding ID document, have had a physical meeting as a further measure of security; currently only possible in Sweden.)

For more detailed information about the Organisation ID Service API, please refer to our REST API Documentation.

Calling the Service

This section describes how to make calls to the Freja eID Organisation ID Service API and process the response.

Initiate Add Organisation ID

This method is used to initiate a transaction for setting an Organisation ID title, identifier name and the identifier itself to a user. The identifier you wish to set must be unique within your system. If you set the Organisation ID for the same user multiple times, the previously set title, identifier name and identifier will be overridden and the last ones you set will be active.

For Integrators/Integrator Relying Parties

Relying Parties which are Integrators must set relyingPartyId per request and that can be done only with a custom request. Read more about how Integrator and Integrated Relying Parties can integrate with Freja here.

/*
* OrganisationId object contains Organisation ID title, identifier name, identifier 
* display types (optional), the identifier and additional attributes (optional).
* If identifier display types contains QR_CODE, it will display QR code containing
* the identifier on user Organisation ID card in Freja eID application.
* Identifier display type TEXT is default value.
* Change values to match your setup.
*/


String organisationIdTitle = "Verisec";
String identifierName = "ID";
String identifier = "vejobla";

List<DisplayType> identifierDisplayTypes = new ArrayList<>();
identifierDisplayTypes.add(DisplayType.QR_CODE, DisplayType.TEXT);

OrganisationIdAttribute organisationIdAttribute =
                OrganisationIdAttribute.create("attribute_id", "attribute name", "attribute value");

List<OrganisationIdAttribute> additionalAttributes = new ArrayList<>();
additionalAttributes.add(organisationIdAttribute);

OrganisationId organisationId = OrganisationId.create(organisationIdTitle, identifierName, identifier, identifierDisplayTypes, additionalAttributes);
 
/*
* Initiate add organisation id request can be created with EMAIL.
* Change value ("joe.black@verisec.com" in the example) to match your setup.
*/

String email = "joe.black@verisec.com";
InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                                                     .createDefaultWithEmail(email, organisationId);
 
/*
* Initiate add organisation id request can be created with SSN.
* Change the ssn value ("123456789001" in the example) and country to match your setup.
*/

SsnUserInfo ssn = SsnUserInfo.create(Country.SWEDEN, "123456789001");
InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                                                         .createDefaultWithSsn(ssn, organisationId);
 
/*
* Initiate add organisation id request can be created with PHONE NUMBER
* by using the custom request builder.
* Change the phone number value ("+467123456789" in the example) to match your setup.
*/

String phoneNum = "+467123456789";
InitiateAddOrganisationIdRequest initAddOrganisationIdRequestCustomPhoneNum = InitiateAddOrganisationIdRequest
                .createCustom()
                .setPhoneNumberAndOrganisationId(phoneNum, organisationId)
                .build();
 
/*
* Initiate add organisation id request can be created with INFERRED
* by using the custom request builder.
*/

InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                .createCustom()
                .setInferredAndOrganisationId(organisationId)
                .build();

/*
* In case of InitiateAdd organisation id method, response type is String.
* The data in this response is the organisation id transaction reference.
*/

String transactionReference = organisationIdClient.initiateAdd(initiateAddOrganisationIdRequest);

When the user has an Organisation ID added, you can initiate organisational transactions. Note that the client has to be initialised as organisational. More details can be found in the Initialising Freja eID Client.

Authentication and signing can be initiated with the Organisation ID identifier.

/*
* Initiate authentication request can be created with ORGANISATION_ID by using the custom request builder.
* Change the value ("vejobla" in the example) to match your setup.
*/

String identifier = "vejobla";
InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest
                .createCustom()
                .setOrganisationId(identifier)
                .build();
String transactionReference = authenticationClient.initiate(initiateAuthenticationRequest);

ORGANISATION_ID_IDENTIFIER and ORGANISATION_ID can be requested as an additional attributes.

/*
* ORGANISATION_ID_IDENTIFIER only contains user's org id identifier
* and ORGANISATION_ID contains user's org id identifier, 
* issuer friendly name (SV and EN localization), additional attributes (if set), 
* and issuer's organisation code (usually null).
* Change the values to match your setup.
*/

String email = "joe.black@verisec.com";
AttributeToReturn[] attributes = {AttributeToReturn.BASIC_USER_INFO,
                                  AttributeToReturn.ORGANISATION_ID_IDENTIFIER}
InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest
                .createCustom()
                .setEmail(email)
                .setAttributesToReturn(attributes)
                .build();
String transactionReference = authenticationClient.initiate(initiateAuthenticationRequest);

AuthenticationResultRequest authenticationResultRequest = 
    AuthenticationResultRequest
        .create(authRef);
AuthenticationResult response = authenticationClient
        .getResult(authenticationResultRequest);
RequestedAttributes requestedAttributes = response
        .getRequestedAttributes();
String organisationIdIdentifier = requestedAttributes.getOrganisationIdIdentifier();
String organistaionIdIdentifierFromOrganisationId = 
requestedAttributes.getOrganisationId().getIdentifier();
String issuerFriendlyNameEn = requestedAttributes
           .getOrganisationId()
           .getIssuerFriendlyName()
           .get(LanguageCode.EN.getName());
String issuerFriendlyNameSv =  requestedAttributes
           .getOrganisationId()
           .getIssuerFriendlyName()
           .get(LanguageCode.SV.getName());
String issuerCode = attributes.getOrganisationId().getIssuerCode();
List<OrganisationIdAttribute> additionalAttributes = requestedAttributes
           .getOrganisationId()
           .getAdditionalAttributes();

Requesting Organisation ID issued by another Relying Party

ORGANISATION_ID_IDENTIFIER or ORGANISATION_ID can be requested even if it is set by another Relying Party. Do this by setting the orgIdIssuer parameter to ANY in initiate authentication or initiate sign requests.

To successfully fetch an Organisation ID set by another Relying Party, that Relying Party must first get in touch with partnersupport@frejaeid.com and give you permission for this request.

Requesting the Minimum Registration Level

When initiating the adding of an Organisation ID, you can request the minimum registration level the user should be on in order to complete the transaction. Supported levels are EXTENDED or PLUS. This parameter is optional. If not forwarded, the default value (EXTENDED) is used.

Setting Expiry Time of the Transaction

You can also set a duration of the transaction. This parameter is optional. If not forwarded, the default value (7 DAYS) is used.

Concerning Integrators/Integrated Relying Parties

For each Integrated Relying Party, as well as the Integrator themselves, Freja eID generates a unique identifier called relyingPartyId. The Integrator needs to pass this identifier in each request. Read more about Integrator Relying Parties here.

Get One Organisation ID Result

This method is used to fetch a single result for a specified add organisation id transaction reference (orgIdRef returned from a call to Initiate Add Organisation ID method).

Integrators must pass relyingPartyId as part of the request.

Get Final Organisation ID Result

This is a blocking method and is used by a Relying Party to fetch a single result with the final status (can be one of: rejected, approved, cancelled or expired) for a specified organisation id reference. The method keeps polling until it receives a final status of the adding organisation id action. If the maximum polling time expires before the action is completed, the method will throw an exception.

Cancel Adding Organisation ID

This method is used to cancel the request to add an Organisation ID to a user.

Update Organisation ID

This method is used to update additional attributes for an issued Organisation ID.
If the attribute specified in the list does not exists for that user, it will be added.
If the attribute specified in the list exists for that user, it will be updated.
If the attribute specified in the list has value null, and exists for that user, it will be deleted.

Response contains information about how many attributes are added, update and/or deleted.

Delete Organisation ID

This method is used to delete an Organisation ID identifier from a user's account. If you only want to override Organisation ID title, identifier name and identifier, use Initiate Add Organisation ID method instead (see above)

Get All Organisation ID Users

This method is used to get information about users who have been assigned an Organisation ID. If there are no users with Organisation ID, an empty list will be returned.

Go to: