Table of contents
Other clients:
Overview
The Freja eID Organisation ID Service allows Relying Parties to set a specific, organisation-related identifier to any user. The end user will have previously downloaded the Freja eID mobile application on one or more iOS or Android devices they possess, and registered an account in Freja eID, allowing Relying Parties 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; this level is only available in Sweden.)
For more detailed information about the Organisation ID Service, 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 by a Relying Party to initiate a transaction for setting an Organisation ID title, identifier name and the identifier itself to a user. The identifier must be unique within the Relying Party's system. If the Organisation ID is set for a user multiple times, the title, identifier name and the identifier will be overridden and the last ones 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 and the identifier. * Change values to match your setup. * See the example below. */ String organisationIdTitle = "Verisec"; String identifierName = "ID"; String identifier = "vejobla"; OrganisationId organisationId = OrganisationId.create(organisationIdTitle, identifierName, identifier); /* * Initiate add organisation id request can be created with EMAIL. * Change value ("joe.black@verisec.com" in the example) to match your setup. * See the example below. */ 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. * See the example below. */ 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. * See the example below. */ 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. * See the example below. */ 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, a Relying Party 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 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. * See the example below. */ String identifier = "vejobla"; InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest.createCustom() .setOrganisationId(identifier) .build(); String transactionReference = authenticationClient.initiate(initiateAuthenticationRequest);
ORGANISATION_ID_IDENTIFIER can be requested as an additional attribute.
/* * Initiate authentication request can be created with ORGANISATION_ID by using the custom request builder. * Change the values to match your setup. * See the example below. */ 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);
Requesting the minimum registration level
When initiating add-on of an Organisation ID, Relying Parties 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. * See the example below. */ 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
A Relying Party can also set a duration of the transaction. This parameter is optional. If it is 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. * See the example below. */ 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 RP, as well for the Integrator RP itself, Freja eID generates a unique identifier called relyingPartyId. The Integrator RP needs to pass this identifier in each request. Read more about Integrator and Integrated 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 by a Relying Party 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. * See the example below. */ 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);
Logging and Error Handling
Details for logging and introduction to client exception can be found in the Logging and Error Handling.