Organisation ID Client : Support Centre

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 Freja eID Relying Party Developers' Documentation.

Calling a 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.

Relying Parties that are Integrators 
must set relyingPartyId per request and that can be done only with a 
custom request. Read more about Integrator Relying Parties 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), 
* organisation code (usually null) and.
* 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 = 
attributes.getOrganisationId().getIdentifier();
String issuerFriendlyNameEn =  attributes
           .getOrganisationId()
           .getIssuerFriendlyName()
           .get(LanguageCode.EN.getName());
String issuerFriendlyNameSv =  attributes
           .getOrganisationId()
           .getIssuerFriendlyName()
           .get(LanguageCode.SV.getName());
String code = attributes.getOrganisationId().getCode();
List<OrganisationIdAttribute> additionalAttributes = attributes
           .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.

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

InitiateSignRequest initSignRequest = 
InitiateSignRequest
                .createCustom()
                .setEmail(email)
                .setDataToSign(dataToSign)
                .setAttributesToReturn(attributes)
                .setOrgIdIssuer(OrgIdIssuer.ANY)
                .build();

In addition, in order for you 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 add-on 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.

/*
* When initiating adding organisation id, you can request the minimum registration level of the user.
*/

String email = "joe.black@verisec.com";
String organisationIdTitle = "Verisec";
String identifierName = "ID";
String identifier = "vejobla";
OrganisationId organisationId = OrganisationId.create(organisationIdTitle, identifierName, identifier);
RegistrationState minRegistrationLevel = RegistrationState.PLUS;
 
InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                .createCustom()
                .setEmailAndOrganisationId(email, organisationId)
                .setMinRegistrationLevel(minRegistrationLevel)
                .build();
String transactionReference = organisationIdClient.initiateAdd(initiateAddOrganisationIdRequest);

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.

/*
* Expiry time is expressed in milliseconds since January 1, 1970, 00:00 UTC.
* Min value is current time +2 minutes, max value is current time +30 days.
*/

Long expiry = Instant.now().plus(3,ChronoUnit.MINUTES).toEpochMilli();
 
String email = "joe.black@verisec.com";
String organisationIdTitle = "Verisec";
String identifierName = "ID";
String identifier = "vejobla";
OrganisationId organisationId = OrganisationId.create(organisationIdTitle, identifierName, identifier);
InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                .createCustom()
                .setEmailAndOrganisationId(email, organisationId)
                .setExpiry(expiry)
                .build();
String transactionReference = organisationIdClient.initiateAdd(initiateAddOrganisationIdRequest);

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

/*
* Parameter relyingPartyId represents a unique ID of the Relying Party
* for which the initiate add organisation id request should be initiated.
*/

String relyingPartyId = "relying_party_id";
 
String email = "joe.black@verisec.com";
String organisationIdTitle = "Verisec";
String identifierName = "ID";
String identifier = "vejobla";
OrganisationId organisationId = OrganisationId.create(organisationIdTitle, identifierName, identifier);
InitiateAddOrganisationIdRequest initiateAddOrganisationIdRequest = InitiateAddOrganisationIdRequest
                .createCustom()
                .setEmailAndOrganisationId(email, organisationId)
                .setRelyingPartyId(relyingPartyId)
                .build();
String transactionReference = organisationIdClient.initiateAdd(initiateAddOrganisationIdRequest);

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).

Integrator Relying Parties have to pass relyingPartyId as part of a request.

/*
* A reference unique to the transaction that can be used to query the result of a transaction.
*/

String orgIdRef ="reference";
  
/*
* In case of getResult method, response type is OrganisationIdResult.
* Response contains add organisation id reference passed during adding organisation id 
* initiation, status of the action and details (can be used for extra validation of response).
* Request contains organisation id transaction reference.
*/

OrganisationIdResultRequest organisationIdResultRequest = OrganisationIdResultRequest.create(orgIdRef);
OrganisationIdResult response = organisationIdClient.getResult(organisationIdResultRequest);
String receivedOrgIdRef = response.getOrgIdRef();
ActionStatus status = response.getStatus();
String details = response.getDetails();

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.

Integrator Relying Parties have to pass relyingPartyId as part of a request.

/*
* A reference unique to the transaction that can be used to query the result of a transaction.
*/

String orgIdRef ="reference";

/*
* A maximum time in seconds to wait for a final status of action
* (to be approved, canceled, rejected or expired).
*/

int maxWaitingTimeInSec = 120;

/*
* In case of pollForResult method, response type is OrganisationIdResult.
* Response contains authentication reference passed during adding organisation id initiation,
* status of the action, details (can be used for extra validation of response).
* If maxWaitingTimeInSec passes and adding organisation id action is not completed
* with one of the final statuses, this method will throw FrejaEidClientPollingException.
*/

OrganisationIdResultRequest organisationIdResultRequest = OrganisationIdResultRequest.create(orgIdRef);
OrganisationIdResult response = organisationIdClient
                                .pollForResult(organisationIdResultRequest, maxWaitingTimeInSec);
String receivedOrgIdRef = response.getOrgIdRef();
ActionStatus status = response.getStatus();
String details = response.getDetails();

Cancel Adding Organisation ID

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

Integrator Relying Parties have to pass relyingPartyId as part of the request

/*
* A reference unique to the transaction that can be used to cancel transaction.
*/

String orgIdRef ="reference";
CancelAddOrganisationIdRequest cancelAddOrganisationIdRequest = CancelAddOrganisationIdRequest
                                                                .create(orgIdRef);
organisationIdClient.cancelAdd(cancelAddOrganisationIdRequest);

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.

Integrator Relying Parties have to pass relyingPartyId as part of the request

/*
* Parameter identifier represents the unique organisation identifier
* set for the end user by the Relying Party.
*/

String identifier = "vejobla";
DeleteOrganisationIdRequest deleteOrganisationIdRequest = DeleteOrganisationIdRequest
                                                          .create(identifier);
organisationIdClient.delete(deleteOrganisationIdRequest);

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.

Integrator Relying Parties have to pass relyingPartyId as part of the request

/*
* Response type is a list of OrganisationIdUserInfo objects.
* OrganisationIdUserInfo contains OrganisationId, SsnUserInfo and RegistrationState objects.
* OrganisationId object contains Organisation ID title, identifier name and the identifier.
* SsnUserInfo object contains ssn and its issuing country.
* RegistrationState is user's registration state.
*/

GetAllOrganisationIdUsersRequest getAllOrganisationIdUsersRequest = GetAllOrganisationIdUsersRequest.create();
 
List<OrganisationIdUserInfo> response = organisationIdClient.getAllUsers(getAllOrganisationIdUsersRequest);

for (OrganisationIdUserInfo organisationIdUserInfo : response) {
    String organisationIdTitle = organisationIdUserInfo.getOrganisationId().getTitle();
    String organisationIdIdentifierName = organisationIdUserInfo.getOrganisationId().getIdentifierName();
    String organisationIdIdentifier = organisationIdUserInfo.getOrganisationId().getIdentifier();
    Country country = organisationIdUserInfo.getSsn().getCountry();
    String ssn = organisationIdUserInfo.getSsn().getSsn();
    RegistrationState registrationState = organisationIdUserInfo.getRegistrationState();
}

Go to:

Organisation ID Client Print

Related Articles