MCP Identity Platform

1. Introduction

This development guide on the Maritime Connectivity Platform identity platform describes the current state of the MCP reference implementation.

Please do not email us directly about usage questions. Instead use our Google Group at https://groups.google.com/forum/#!forum/maritimeconnectivity for general usage questions. In this way future users can see answers to commonly asked questions. Google Groups is also where we post information about new releases and updated documentation.

This developer guide is intended to make you familiar with developing secure applications and services for MCP in particular with regards to Identity Management.

1.1. A Bit of History

The Maritime Connectivity Platform project started out as an internal project at the Danish Maritime Authority in the autumn of 2012. As part of the e-Navigation process the Danish Maritime Authority had been working on an e-Navigation Prototype Display system called EPD. The EPD consist of two applications for demonstrating potential e-navigation solutions. An ECDIS like ship side application and a shore side application.

During the development it was clear that AIS was a severe limiting factor when communicating between the ship side and the shore side. Putting a lot of limitations of the different kind of maritime services that could be developed. Especially three issues was identified.

Lack of bandwidth. Only limited amounts of data could be transfered. Often using complex encoding schemes such as application specific AIS messages.
Ease of development. There was no easy way to simulate AIS communication without a very complex developer environment.
Limited Signal Coverage. There are certain types of services where the actors communicating might not all be within reach of radio signals.

The first prototype was built in the winter of 2012 and was implemented in the EPD in spring 2013. It just featured basic point to point communication. This is basically what is the Maritime Message Service now. During the summer of 2013 the vision for a general framework for maritime communication was created. Including registries for services and identities in addition to the message based framework. It also got its name the “Maritime Connectivity Platform” as a sort of umbrella name for the various underlying services. In 2014 the first release of the MCP reference implementation was made available for the public.

1.2. Overview

Here is a 10000 foot overview of MCP:

There are 3 different core services provided by MCP

Maritime Identity Registry. A centralized authority for identities of persons, organizations or ships that are using the MCP.
Maritime Service Registry. A centralized repository of service standards and provisioned services world wide.
Maritime Messaging Service (MMS). A communication protocol on top of TCP/IP. Supporting reliable delivery of messages and geocasting^[1].

This guide will predominantly discuss the identity registry.

1.3. Signing up

In order to get an organization, its users and any ships the organization might own on to the MCP, the organization needs to perform a signup process. The process is currently manual. To start the process, please fill out the registration form.

Once your organization has been approved you will have access to MCP and its services. You should probably start by looking at the Management Portal. See the manual for how to use it.

1.4. Feedback

Readers may send feedback about errors, omissions, and ambiguities in this guide to oliver@dmc.international or even better submit a pull request to the documentation available at https://github.com/MaritimeConnectivityPlatform/developers.maritimeconnectivity.net.

As previously mentioned questions about usage of MCP should be directed to our Google Group at https://groups.google.com/forum/#!forum/maritimeconnectivity

2. Identity Management

Identity management refers to the process of employing technologies to manage information about the identity of users and control access to company resources. The goal of identity management is to improve productivity and security while lowering costs associated with managing users and their identities, attributes, and credentials.

The goal of the MCP Identity Registry is to create a solution that satisfies the most common identification needs for the entire maritime industry on a global scale.

This is not a simple task as any solution must support every possible user scenarios from small leisure sailors to multinational companies. The complexity of this task is why the functionality will be delivered over multiple milestones in the coming years. The most important things such as support for authentication will be implemented first. Additional functionality will be added based on user needs in the projects supported by MCP.

2.1. The Identity Registry

In most of the documents that describe MCP there is the concept of an Identity Registry. In reality there are numerous systems both internal to MCP as well as external to MCP that makes up the identity registry. The main components of the Identity Registry are:

The Identity Registry API
The Identity Broker

The Identity Registry API provides management of entities in MCP and will be described later in this document.

The Identity Broker provides links to trusted Identity Providers, owned by maritime organizations that wish to connect its users to MCP. Within the scope of the EfficienSea 2 and STM validation projects, a special Identity Provider is available where organizations can create users without linking their own Identity Provider.

This will enable the participants in the projects to register actors to validate specific service concepts in testbed trials or utilize the operational services established by the projects, as well as validate the identity management concept of MCP. Beyond the scope of the project, it is foreseen that several identity registers will collaborate to form the global federated MCP Identity Registry.

2.2. Key Actor Concepts

In order to be able to describe some of the concepts we are working with, here is a short introduction of the various actors we envision will interact with the identity registry.

Identity management and security is a very complex and comprehensive field. So wherever possible we must limit non-essential functionality. So clearly, there are some maritime entities that should not be a part of the identity registry. Therefore, the Identity Registry should not be:

Managing information about entities that does not need to have access rights. For example, route or container information. While information about routes can be accessed by various users and systems. Routes by them self does not need access rights to access other information. It is only users and systems/devices that need access right.
Maintaining information about entities that are not security related. For example, business addresses of users and organizations. Or location information about entities that can be used, for example, for routing messages to the right location.

The main reason for excluding all but non-essential security related information is that it opens up the never ending discussion about what exactly should be maintained in the identity registry. If we make a generalized information store that maintains and provides query capabilities for all kinds of information about users and systems/devices. For example, business addresses, geographical location. We might as well use this functionality for storing other queryable information. For example, maintaining information about routes or cargo.

This does not prohibit a later revisiting of these goals. Or prohibit including work from other groups into a general framework at a later time. But for time being the identity registry will revolve about the 5 entities listed below.

2.2.1. Organization

In MCP an organization is an entity, such as an institution, company or an association, that has a collective goal and is linked to an external environment. Examples, include international organizations such as IMO, IALA, IHO. National authorities such as US Coastguard, Swedish Maritime Administration. Local authorities such as VTS-Oeresund, Port of Rotterdam, Hong Kong SAR. Or commercial companies such as Transas or Maris.

In order to be able to use the functions of MCP in any way, an organization needs to be signed up to MCP. In the context of the EfficienSea 2.0 and STM projects, this is currently done be sending an email with various information about the organization to a MCP test bed administrator.

In the future a more automated process involving a validation workflow by some organization may validate the relationship between an organization in the real world, and the issued maritime digital identity. How this validation is to take place is still up for discussion. However, one possible solution would be for the maritime authorities in which a given organization is registered to put the stamp of approval on the signup application.

Once an organization has been registered (and validated), an identity administrator of that organization will be able to create and manage maritime identities that belong to this organization, such as Users, Vessels Devices or Services. This administration is typically done via MCP Portal which is a web based client. For some larger organizations it might make sense to integrate directly via the underlying APIs.

All organizations that are registered in MCP must be registered with a unique MRN.

The MRN is used in numerous places. For example, all service specifications from a given organization includes the organizations MRN.

Examples of valid organization ids:

urn:mrn:mcl:org:imo
urn:mrn:mcl:org:iala
urn:mrn:mcl:org:dma
urn:mrn:mcl:org:portofrotterdam
urn:mrn:mcl:org:vts-oeresund
urn:mrn:mcl:org:amsa@iala

MRN has been approved by IANA as an official URN namespace. For more information on the MRN specification you can read more at https://www.iana.org/assignments/urn-formal/mrn

2.2.2. Vessels

Vessels describe any floating object used for the carriage of people or goods.

The main need for registering vessels in MCP is so that digital authentication certificates can be issued for them. Thereby enabling secure communication between vessels as well as digitally signing of documents. Users might also use these authentication certificates for other purposes. The important thing is that the functionality is there.

As part of the authentication certificate of a vessel its name, MMSI number, IMO number, callsign and possible other attributes are included in the header of the authentication certificate.

2.2.3. Services

Services refer to digital services. For example, a weather service that is available to other services for machine to machine communication. Services need to be registered in such a way that it can successfully authenticate users.

2.2.4. Users

Users mainly refer to human users. Human users differ from other actors in that they typically use a username/password to login which implies a different interaction pattern with the identity registry than say communication between vessels.

2.2.5. Devices

Devices can be any number of entities that are not covered by the other entity types. It could for example be a lighthouse, an ECDIS or a server that needs to be able to authenticate itself.

2.2.6. MMS

Maritime Messaging Service (MMS) is defined as an entity and a MCP-specific connectivity component hosted by an organization.

3. Authentication

Authentication is any process by which a system verifies the identity of a user (human or machine) who wishes to access it. Since access control is normally based on the identity of the user who requests access to a resource, authentication is essential to efficient security. In contrast to identification which refers to the act of stating a person or thing’s identity, authentication is the process of actually confirming the stated identity. It might involve verifying the authenticity of a website by a digital certificate that it provides, or validating a persons identity documents.

3.1. Overview

The way in which a human user or machine may be authenticated typically falls into three different categories, based on what is commonly known as the factors of authentication: something the user knows, something the user has, and something the user is. Each authentication factor covers a range of elements used to authenticate or verify a person’s identity prior to being granted access, approving a transaction request, signing a document or other work product, granting authority to others, and establishing a chain of authority.

Knowledge factors: Passwords, passphrases, pins, challenge response,
Ownership factors: ID card, Cell phone, authentication certificates,
Inheritance factors: Fingerprint, retinal patterns, face, voice,

Currently the implementation effort in MCP is concentrating on passwords for human users and authentication certificates for machine users. In the future we will probably add more methods.

While the difference of using authentication certificates or passwords might seem minor from a user perspective the underlying implementation and usage is radically different which is why it has been split into different sections.

4. Brokered User Federation

In the previous section we discussed digital certificates for use in machine to machine communication. There are no technical reasons to why human users should not be able to use digital certificates to authenticate themselves as well. However, there are some serious practical issues that make it difficult to see them as a general solution for human user authentication. The first issue being that it requires that the certificate must always be present on the computer or mobile phone from which access is made. This is normally not a problem for machine to machine communication. Because, once installed the hardware configuration almost never changes. Unlike human users that use their computer during the day to access information, their mobile phone on the way back from work and their tablet in the evening from home. Making sure that certificates are installed on all these devices and refreshing them once they expire is a lot of effort to require from users. We believe having such a complicated setup would be a major barrier towards successful adoption of MCP. So for now, authentication of human users in MCP will be based on login through a web browser, using brokered federation.

Federation is the means of linking distinct identity management systems to a person’s electronic identity and attributes. For example, a shipping company might expose all their users in LDAP or Active Directory to MCP in such a way as they appear as MCP users. Thereby bypassing the need to manage their users directly in MCP. This also means that MCP is not responsible for management of users. In practical terms, federation means that users asked to authenticate in MCP will be redirected to a login webpage supplied by their organization where they can login using their organizational id.

Since the authentication process is the responsibility of the organizations, it is also up to the individual organizations to choose an appropriate authentication method. While most will likely use classic username/password authentication, multi factor security, biometric security or other approaches could be used.

4.1. OpenID Connect

OpenID Connect is the protocol chosen to be used for user federation in MCP, and it should be supported by Service Providers. It is an interoperable authentication protocol based on the OAuth 2.0 family of specifications. It uses straightforward REST/JSON message flows with a design goal of "making simple things simple and complicated things possible". It’s uniquely easy for developers to integrate, compared to any preceding Identity protocols.

OpenID Connect lets developers authenticate their users across websites and apps without having to own and manage password files. For the app builder, it provides a secure verifiable, answer to the question: "What is the identity of the person currently using the browser or native app that is connected to me?"

OpenID Connect allows for clients of all types, including browser-based JavaScript and native mobile apps, to launch sign-in flows and receive verifiable assertions about the identity of signed-in users.

OpenID Connect provides authentication details in JWT tokens, that can be encrypted or digitally signed.

4.2. MCP User Federation Setup

In most federated setups there is 1 step from the website (Service Provider) that need authentication and the Identity Provider, normally presented with a "Log in with X" link, where X could be Facebook, Google, etc. The setup used in MCP has 2 steps, where the first step is MCP Identity Broker which presents the user with a list of available Identity Providers, which is the second step. For a deeper understanding of how this is actually done please read the Identity Broker overview section from the Keycloak manual. Keycloak is the software used for MCP Identity Broker.

MCP expects the following attributes in the OpenID Connect JWT Access Token:

Attribute	Description
preferred_username	The username of the user in the parent organization.
email	The email of the user.
given_name	Firstname of the user.
family_name	Lastname of the user.
name	Full name of the user.
org	The Maritime Resource Name of the organization the user is a member of.
permissions	List of permissions for this user assigned by the organization the user is a member of.
mrn	The Maritime Resource Name of the user.

Attribute

Description

preferred_username

The username of the user in the parent organization.

The email of the user.

given_name

Firstname of the user.

family_name

Lastname of the user.

name

Full name of the user.

org

The Maritime Resource Name of the organization the user is a member of.

permissions

List of permissions for this user assigned by the organization the user is a member of.

mrn

The Maritime Resource Name of the user.

These attributes will be directly mapped from attributes provided by the organizations Identity Provider, so the Identity Provider must also provide these attributes, except for the "org"-attribute.

4.3. OpenID Connect Authentication Flow

To illustrate the authentication flows the sequence diagrams below is provided.

The first diagram below shows the standard OpenID Connect Authorization Code Flow involving a browser being used by the user to access a service in the form of a webpage.

Authentication flow

The second diagram shows the flow used when an authenticated user is accessing a backend service. For browser based services this scenario is often used when the browser retrieves data from backend services. In this scenario since the user is authenticated, the user has a token that is presented for authentication for the backend service.

Backend service authentication flow

4.4. Keycloack

Keycloak is one of many products that includes support for OpenID Connect, and it is the product that currently provides MCP Identity Broker which is the cornerstone in MCP user federation.

Keycloak is an open source product developed by RedHat. Keycloak can be set up to work in different ways. It can be set up as an Identity Broker in which case it will link to other Identity Providers, which is what MCP Identity Broker does, or it can be set up to work as an Identity Provider, using either a database or LDAP/AD as a backend. Due the ability to connect to LDAP/AD, Keycloak can be used as quick and easy way to set up a Identity Provider.

4.5. Getting connected to MCP

If your organizations wishes to connect to MCP as an Identity Provider, to enable your uses to authenticate in MCP, please contact Oliver Haagh at oliver@dmc.international in order to set it up. Note that currently you need to expose interfaces that supports either OpenID Connect or SAML2.

Within the scope of the EfficienSea2 and STM validation projects, organizations can get users registered in special project Identity Providers, supplied by MCP. To join MCP please fill out the form at Apply.

4.5.1. Setting up an OpenID Connect Identity Provider

OpenID Connect is supported by the latest ADFS and Keycloak releases. MCP Identity Broker only supports the OpenID Connect Authorization Code Flow when connecting to Identity Providers. This limitation only applies when the Identity Broker connects to Identity Providers, not when Services/Clients connects to the Identity Broker.

As default MCP Identity Broker expect the following attributes to be provided by an OpenID Connect Identity Provider:

Attribute	Description
preferred_username	The username of the user in the parent organization.
email	The email of the user.
given_name	Firstname of the user.
family_name	Lastname of the user.
name	Full name of the user.
permissions	List of permissions for this user assigned by the organization the user is a member of.

Attribute

Description

preferred_username

The username of the user in the parent organization.

The email of the user.

given_name

Firstname of the user.

family_name

Lastname of the user.

name

Full name of the user.

permissions

List of permissions for this user assigned by the organization the user is a member of.

If your Identity Provider has the values in different attributes, some mapping can be set up.

The Identity Broker will generate and attach the organizations MRN and the users MRN to the user.

4.5.2. Setting up an OpenID Connect Identity Provider for multiple organizations

MCP has some special Identity Providers that handles the authentication for multiple organizations. Current examples are "IALA" and "BIMCO ExtraNet". These Identity Providers are responsible for vetting the organizations they provide authentication for, so that it is confirmed that the organization is who they claim to be. New organizations can be added by these Identity Providers. Since MCP currently needs to know about organizations centrally to be able to (among other things) issue certificates, some extra information is needed from these Identity Providers, to be able to create them in the central Identity Registry, if they are not already known.

The extra information must be given as attributes, in addition to the attributes mentioned in Setting up an OpenID Connect Identity Provider:

As default MCP Identity Broker expect the following attributes to be provided by an OpenID Connect Identity Provider:

Attribute	Description
mrn	The Maritime Resource Name of the user.
org	The Maritime Resource Name of the parent organization of the user.
org-name	Human readable name of the parent organizations.
org-address	Address of the organization. It must be without linebreaks, ending with comma and the country of the address.

Attribute

Description

mrn

The Maritime Resource Name of the user.

org

The Maritime Resource Name of the parent organization of the user.

org-name

Human readable name of the parent organizations.

org-address

Address of the organization. It must be without linebreaks, ending with comma and the country of the address.

Note that the MRN must be on the form "urn:mrn:mcl:user:dma@iala:thc" and "urn:mrn:mcl:org:dma@iala" for user and organization respectively. In this case the organization is "dma" whos identity is guaranteed by "iala".

4.5.3. Setting up an SAML2 Identity Provider

SAML2 is supported by older ADFS releases.

Attribute	Description
NAMEID	The username of the user in the parent organization.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	The email of the user.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	Firstname of the user.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	Lastname of the user.
http://schemas.microsoft.com/ws/2008/06/identity/claims/role	List of permissions for this user assigned by the organization the user is a member of.

Attribute

Description

NAMEID

The username of the user in the parent organization.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

The email of the user.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Firstname of the user.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Lastname of the user.

http://schemas.microsoft.com/ws/2008/06/identity/claims/role

List of permissions for this user assigned by the organization the user is a member of.

If your Identity Provider has the values in different attributes, some mapping can be set up.

The Identity Broker will generate and attach the organizations MRN and the users MRN to the user.

5. PKI and X.509 Certificates

A Public Key Infrastructure (PKI) is a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital authentication certificates and manage public-key encryption. Thereby helping an organization establish and maintain a trustworthy networking environment. There is no inherent requirement for using a PKI based solution for enabling secure machine to machine (M2M) communication, but it is the most commonly used solution and lots of software, standards and best practices exists for utilizing it. The choice of using PKI based on the X.509 standard for M2M communication in MCP was thus straightforward.

The key piece in a PKI architecture is a PKI CA (Certificate Authority) which is an entity that issues digital authentication certificates. A digital certificate that certifies the ownership of a public key by the named subject of the certificate. An obvious example would be creating a certificate for a vessel, which can serve to certify that a given document was indeed signed by someone in possession of the certificate issued to that vessel.

One of the most important aspects of designing a PKI based architecture is the certificate hierarchy planning because the design will affect how certificates are validated and used by PKI-enabled actors. Normally a PKI based architecture is arranged in a tree like hierarchy with a single root entity in the top and with numerous leaves called sub CAs. Each sub CA can have their own sub CA thereby forming a tree with a single entity at the top. Each leave in the tree is responsible for creating certificates, for example, ships or organizations. The reason for doing this is to be able to delegate the responsibility to different parties. For example, in the case of MCP one could envision that at some point in the future every flag state would be their own sub CA. Having the sole responsibility of issuing certificates for vessels registered under their own flag.

PKI hierarchy

In the current version of MCP we are working with four sub CAs that have the responsibility for issuing all certificates. The four sub CAs are IALA, BIMCO, SMART Navigation Project and the MCP Identity Registry itself.

The most important functionality of a CA is issuing digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate. This allows others (relying parties) to rely upon signatures or on assertions made about the private key that corresponds to the certified public key. In this model of trust relationships, a CA is a trusted third party—trusted both by the subject (owner) of the certificate and by the party relying upon the certificate. In the case of MCP these certificates are typically used to make secure connections between maritime actors over the Internet. A certificate is required in order to avoid the case that a malicious party which happens to be on the path to the target server pretends to be the actual target. Such a scenario is commonly referred to as a man-in-the-middle attack. The client uses the CA certificate to verify the CA signature on the server certificate, as part of the checks before establishing a secure connection. Likewise, the server has the option of inspecting the clients certificate before allowing it to connect.

To issue a new certificate for, for example, a vessel an administrator for the organization who owns the ship will need to log in to MCP Portal and use its functionality for issuing new certificates. The certificate being issued will contain information about the name of the ship, the owner, the flag state and other attributes such as MMSI and IMO number. In the current implementation there is no validation of this information other than that the organization must have been accepted when signing up. We do not expect this to be a problem for the foreseeable future as the number of participating parties is still relatively small. In the future where many more organizations have been added it might, for example, be possible to integrate with national registries so an automated checks of these information can be made.

After having issued a certificate the administrator can now install it on the ship in some way. The actual logistics about how and where to install it is outside of the scope of the identity registry as this might vary a lot between organizations and projects. This also reduces the functionality of the identity registry to just provide the core functionality of Identity management allowing users to be able to build innovative solutions on top of it. This also applies directly to machine to machine communication. The identity registry places no restrictions about what kind of machine to machine communication protocols that should be used, it just provides the basic infrastructure to allow for each machine to authenticate the host in the other end. Letting each project select their protocols if needed.

5.1. Get MCP Root Certificate

In order to use the certificates issued by the MCP Identity Registry it is needed to add MCP Root Certificates to the relevant trustchain. Here you can download the root certificates for MCP instances:

MCP Production environment root certificates as PEM (one file, primarily for Apache/Nginx), in JKS (for Java) or a zip with the separate files (for windows).

MCP Staging environment root certificates as PEM (one file, primarily for Apache/Nginx), in JKS (for Java) or a zip with the separate files (for windows).

MCP Test environment root certificates as PEM (one file, primarily for Apache/Nginx), in JKS (for Java) or a zip with the separate files (for windows).

5.2. Certificate Attributes

MCP can issue X.509 certificates for the users which can then be used for authentication. Service providers relying on X.509 certificate authentication must obtain and install MCP root certificate into their webservice.

The standard information present in an X.509 certificate includes:

Version – which X.509 version applies to the certificate (which indicates what data the certificate must include)
Serial number – A unique assigned serial number that distinguishes it from other certificates
Algorithm information – the algorithm used to sign the certificate
Issuer distinguished name – the name of the entity issuing the certificate (MCP)
Validity period of the certificate – start/end date and time
Subject distinguished name – the name of the identity the certificate is issued to
Subject public key information – the public key associated with the identity

The Subject distinguished name field will consists of the following items:

Field	User	Vessel	Device	Service	MMS	Organization
CN (CommonName)	Full name	Vessel name	Device name	Service Domain Name	MMS name	Organization Name
O (Organization)	Organization MRN
OU (Organizational Unit)	"user"	"vessel"	"device"	"service"	"mms"	"organization"
E (Email)	User email					Organization email
C (Country)	Organization country code
UID	Entity MRN	Organization MRN

Field

User

Vessel

Device

Service

MMS

Organization

CN (CommonName)

Full name

Vessel name

Device name

Service Domain Name

MMS name

Organization Name

O (Organization)

Organization MRN

OU (Organizational Unit)

"user"

"vessel"

"device"

"service"

"mms"

"organization"

E (Email)

User email

Organization email

C (Country)

Organization country code

UID

Entity MRN

Organization MRN

An example of the fields for a vessel could look like this:

C=DK, O=urn:mrn:mcl:org:dma, OU=vessel, CN=JENS SØRENSEN, UID=urn:mrn:mcl:vessel:dma:jens-soerensen

Finally, In additions to the information stored in the standard X.509 attributes listed above, the X509v3 extension SubjectAlternativeName (SAN) extension is used to store extra information. There already exists some predefined fields for the SAN extension, but they do not match the need we have for maritime related fields. Therefore the “otherName” field is used, which allows for using a Object Identifier (OID) to define custom fields. The OIDs currently used are not registered at ITU, but are randomly generated using a tool provided by ITU (see http://www.itu.int/en/ITU-T/asn1/Pages/UUID/uuids.aspx). See the table below for the fields defined, the OIDs of the fields and which kind of entities that uses the fields.

Name OID Used by

Name	OID	Used by
Flagstate	`2.25.323100633285601570573910217875371967771`	Vessels, Services
Callsign	`2.25.208070283325144527098121348946972755227`	Vessels, Services
IMO number	`2.25.291283622413876360871493815653100799259`	Vessels, Services
MMSI number	`2.25.328433707816814908768060331477217690907`	Vessels, Services
AIS shiptype	`2.25.107857171638679641902842130101018412315`	Vessels, Services
Port of register	`2.25.285632790821948647314354670918887798603`	Vessels, Services
Ship MRN	`2.25.268095117363717005222833833642941669792`	Services
MRN	`2.25.271477598449775373676560215839310464283`	Vessels, Users, Devices, Services, MMS
Permissions	`2.25.174437629172304915481663724171734402331`	Vessels, Users, Devices, Services, MMS
Subsidiary MRN	`2.25.133833610339604538603087183843785923701`	Vessels, Users, Devices, Services, MMS
Home MMS URL	`2.25.171344478791913547554566856023141401757`	Vessels, Users, Devices, Services, MMS
URL	`2.25.245076023612240385163414144226581328607`	MMS

Flagstate

2.25.323100633285601570573910217875371967771

Vessels, Services

Callsign

2.25.208070283325144527098121348946972755227

Vessels, Services

IMO number

2.25.291283622413876360871493815653100799259

Vessels, Services

MMSI number

2.25.328433707816814908768060331477217690907

Vessels, Services

AIS shiptype

2.25.107857171638679641902842130101018412315

Vessels, Services

Port of register

2.25.285632790821948647314354670918887798603

Vessels, Services

Ship MRN

2.25.268095117363717005222833833642941669792

Services

MRN

2.25.271477598449775373676560215839310464283

Vessels, Users, Devices, Services, MMS

Permissions

2.25.174437629172304915481663724171734402331

Vessels, Users, Devices, Services, MMS

Subsidiary MRN

2.25.133833610339604538603087183843785923701

Vessels, Users, Devices, Services, MMS

Home MMS URL

2.25.171344478791913547554566856023141401757

Vessels, Users, Devices, Services, MMS

URL

2.25.245076023612240385163414144226581328607

MMS

Encoding of string values in certificates must follow the specifications defined in RFC 5280, and where possible it is highly recommended to use UTF-8.

5.3. Revocation of certificates

A crucial part of any PKI is to support revocation of certificates, so that certificates that belongs to entities who is no longer trusted, affiliation has change, etc., can be mark as not trusted any more. Anyone who wishes to validate a certificate can then check if the certificate has been marked as revoked. The checking of the certificate revocation status can be done in two ways:

Call the OCSP interface provided by the Identity Registry for each certificate.
Periodically download a Certificate Revocation File from the Identity Registry and use it check certificates locally.

The endpoints for both the OCSP interface and the Certificate Revocation File are embedded into the certificates issued by MCP Identity Registry, and are currently http://api.maritimeconnectivity.net/x509/api/certificates/crl and http://api.maritimeconnectivity.net/x509/api/certificates/ocsp.

5.4. Certificate Authentication Flow

To illustrate the authentication flow the sequence diagram below is provided.

5.5. Obtaining a OpenId Connect Token using a Certificate

It is possible to obtain OpenID Connect Tokens using certificate authentication. The idea is that instead of authenticating by being redirected to an Identity Provider as in the normal OpenID Connect flow, you authenticate at the Identity Broker by using your certificate (that has been issued by MCP Identity Registry). This authentication would work in the same way as when authenticating to any service. When authentication has been succesful the Identity Broker can then issue a JWT-token, which is what the OpenId Connect authentication use. So in effect what we have is a "bridge" between the 2 authentication approaches.

An example of use could be that a device (which has been issued certificates) wishes to authenticate securely with a service, but the service only supports OpenId Connect authentication. Using the approach mentioned above, the device can use its certificate to get an OpenId Connect token, which can then be used to authenticate to the service.

The flow looks like the diagram below:

5.5.1. Example of Obtaining a OpenId Connect Token using a Certificate

In this simple example we will assume that a certificate and key—pair has been issued to the entity who wishes to authenticate. This example makes use of curl a commandline tool available on Linux and Mac OS X.

The authentication involves 2 steps:

Obtaining a temporary Authorization Code using a certificate.
Obtaining a OpenId Connect Token using the Authorization Code.

These 2 steps are actually standard in the OpenID Connect Authorization Code Flow, though normally certificates are not the standard authentication method.

First we obtain the code by issuing this command:

curl --verbose --location --cookie "" --key PrivateKey.pem --cert Certificate.pem 'https://maritimeid.maritimeconnectivity.net/auth/realms/MCP/protocol/openid-connect/auth?client_id=cert2oidc&redirect_uri=http%3A%2F%2Flocalhost%3A99&response_type=code&kc_idp_hint=certificates&scope=openid'

Let us break down the command:

curl --verbose --location --cookie "": curl is the tool itself. --verbose means it will be in verbose mode, --location means curl will follow HTTP redirects and --cookie "" activates the use of HTTP cookies which means that cookies received will be remember and used during redirects. We need to follow redirects since that is used by OpenID Connect to go back and forth between servers, and the verbose mode is needed because we would like to see where we are redirected — especially the last redirect, but more about that later.
--key PrivateKey.pem --cert Certificate.pem: Here the private key and the certificate is given to curl in PEM format.
The last part is the URL which itself is multiple parts:
- Address of the authentication endpoint: https://maritimeid.maritimeconnectivity.net/auth/realms/MCP/protocol/openid-connect/auth
- Parameters: client_id=cert2oidc&redirect_uri=http%3A%2F%2Flocalhost&response_type=code&kc_idp_hint=certificates&scope=openid. These can be also be broken down:
  - client_id=cert2oidc: This is a special OpenID Connect client setup to be used for certificate authentication.
  - redirect_uri=http%3A%2F%2Flocalhost%3A99: This is where the authentication server will redirect to at the end of the authentication. The parameter is URL encoded and decoded looks like this: http://localhost:99. This address is meant to be invalid, since we want the last redirect to fail.
  - response_type=code: This defines that we uses the Authorization Flow as mentioned above.
  - kc_idp_hint=certificates: This tells the Identity Broker that we wants to authenticate using the Certificate Identity Provider.
  - scope=openid: And finally, this define that we are using OpenID Connect.

When the command runs it returns a lot of output, due to being in verbose mode. We will not go into detail, but quite a few redirects happens, as described in the sequences diagram above. The last redirect however fails, which is intended. The final output will look something like this:

* Issue another request to this URL: 'http://localhost:99?code=uss.Yw6k4rXOJiR6IF4a2Y7tYC1-Eqoo8dHSUwjfuIFDfpI.543a63db-9d22-45f7-85b6-a258059c0825.6826c662-6b68-423a-a248-71bd3e69dab0'
* Rebuilt URL to: http://localhost:99/?code=uss.Yw6k4rXOJiR6IF4a2Y7tYC1-Eqoo8dHSUwjfuIFDfpI.543a63db-9d22-45f7-85b6-a258059c0825.6826c662-6b68-423a-a248-71bd3e69dab0
*   Trying 127.0.0.1...
* connect to 127.0.0.1 port 99 failed: Connection refused
* Failed to connect to localhost port 99: Connection refused
* Closing connection 1
curl: (7) Failed to connect to localhost port 99: Connection refused

Here we can recognize http://localhost:99 from the redirect_uri parameter described earlier. We can also see that a code parameter is in the url, in this case with the value uss.Yw6k4rXOJiR6IF4a2Y7tYC1-Eqoo8dHSUwjfuIFDfpI.543a63db-9d22-45f7-85b6-a258059c0825.6826c662-6b68-423a-a248-71bd3e69dab0. It is this code we need to in the second step of authentication to get the OpenID Connect Tokens. The code is only valid for a very limited time (less than a minute) and can only be used once. We will again use curl in the second step:

curl --data "grant_type=authorization_code&client_id=cert2oidc&code=uss.Yw6k4rXOJiR6IF4a2Y7tYC1-Eqoo8dHSUwjfuIFDfpI.543a63db-9d22-45f7-85b6-a258059c0825.6826c662-6b68-423a-a248-71bd3e69dab0&redirect_uri=http%3A%2F%2Flocalhost%3A99" https://maritimeid.maritimeconnectivity.net/auth/realms/MCP/protocol/openid-connect/token

Again, let us break down the command. In this case the command consist of 3 parts, curl — the tool itself, data-parameters and an URL. We will concentrated on the data-parameters. Note that this is a HTTP POST request, which is why the parameters is supplied in a separate argument and not as part of the URL.

grant_type=authorization_code: This specifies that we will use an authorization code to authenticate ourself in this call.
client_id=cert2oidc: The id of the special client, as mentioned above.
code=uss.Yw6k4rXOJiR6IF4a2Y7tYC1-Eqoo8dHSUwjfuIFDfpI.543a63db-9d22-45f7-85b6-a258059c0825.6826c662-6b68-423a-a248-71bd3e69dab0: The code we obtained earlier.
redirect_uri=http%3A%2F%2Flocalhost%3A99: The redirect url, the same as before, though not used for actual redirection in this case.

When this call runs there will be no redirection, so we do not need to tell curl to follow redirects. Instead the returned output will be the tokens that we wish to use, in a format like this:

{
   "access_token":"eyJhbGciOiJ...uXoHudIM1yiDBYj8g",
   "expires_in":300,
   "refresh_expires_in":1800,
   "refresh_token":"eyJhbGciOiJ...iv7rKSa__IKy983Gg",
   "token_type":"bearer",
   "id_token":"eyJhbGciOiJ...Ycp2GupfpTTgRkhtnw",
   "not-before-policy":0,
   "session_state":"94487eaa-b77f-4b6c-8db1-c574fc6a09da"
}

The access_token is the token that should be used we communicating with services in MCP context. The token should be embedded in the HTTP header. When using curl it can be done like this:

curl -H "Authorization: Bearer eyJhbGciOiJ...uXoHudIM1yiDBYj8g" https://api.maritimeconnectivity.net/oidc/api/org/DMA

The refresh_token is used to re-authenticate to get a new set of tokens when the access_token has expired, in this case 300 seconds after it has been issued, as seen in the expires_in attribute. The new set of tokens can then be obtain with a HTTP POST like this:

curl --data "grant_type=refresh_token&client_id=cert2oidc&refresh_token=eyJhbGciOiJ...iv7rKSa__IKy983Gg" https://maritimeid.maritimeconnectivity.net/auth/realms/MCP/protocol/openid-connect/token

6. Authorization

Another central aspect of Identity Management is the concept of authorization which is the process of determining a set of permissions that is granted to a specific trusted identity. In all practical senses, authorization follows authentication. Once a system knows who you are, the system can determine what is appropriate for you to be able to see or do. authorization can be determined based on the user identity alone, but in most cases requires additional attributes about the user, such as role, title, flag state, etc.

Authorization can typically be handled in two ways.

Locally by the application or service that is being accessed.
Centralizing the authorization policy decisions regardless of the location of the user or the application/service

Since authorization can always be done locally by the application that is being accessed, for example by storing user rights in a local database, we have decided that MCP will not prioritize central support for authorization for the next milestones. Instead focusing on getting authentication right.

Before implementation of centralized support for authorization can begin there are some obstacles that lie ahead. Mainly because there, unlike authentication, are no good standards for doing authorization.

Even though there are no real standards there are a number of approaches that are commonly used. The most commonly used probably being role-based access control (RBAC). RBAC is an access control mechanism defined around roles and privileges. The components of RBAC such as role-permissions, user-role and role-role relationships make it simple to do user assignments of entitlements. However, adopting RBAC for MCP opens some questions. For example, who defines the roles and are they global roles. Or are they local to a particular service or a particular organization. For example, an "administrator" role might entail a list of certain privileges in one organization and another list of privileges in another organization.

Given these issues and many other we have to decide not to implement central authorization in MCP. Instead MCP will provide the information that can be used for authorization in the services.

As described in the sections about [OpenID Connect] and [Certificate Attributes], both authentication methods provides information about the authenticated user that can be used for authorization:

The organization the entity belong to.
The permissions/roles/groups the entity has been assigned by the organization.

When an organization wishes to use a service, the organization will then make an agreement with that about how access levels shall be defined in that service, based on the permissions. This will have to be done for each service the organization wishes to use.

6.1. Example of Authorization

As an example of how authorization can be done, let us have a look at how it is handled inside the MCP Identity Registry. When it comes to authorization, the Identity Registry will have the same information about its users as any other service in MCP.

The Identity Registry currently has these roles:

Identity Registry Roles
Role	Approve New Org	Edit Own Org	Maintain Org Users	Maintain Org Vessels	Maintain Org Services	Maintain Org Devices	Maintain Org MMS	Maintain Org Roles	Delete Org
ROLE_SITE_ADMIN	X	X	X	X	X	X	X	X	X
ROLE_ORG_ADMIN		X	X	X	X	X	X	X
ROLE_ENTITY_ADMIN			X	X	X	X	X
ROLE_USER_ADMIN			X
ROLE_VESSEL_ADMIN				X
ROLE_SERVICE_ADMIN					X
ROLE_DEVICE_ADMIN						X
ROLE_MMS_ADMIN							X
ROLE_APPROVE_ORG	X
ROLE_USER

A few things should be noted:

"Maintain" (as mentioned in the table above) means to be able to create, update and delete, as well as issuing and revoking certificates.
Excluding entities with the role ROLE_SITE_ADMIN, it is not possible for entities to see entities from other organizations.
A ROLE_SITE_ADMIN can maintain entities and organizations beyond his own organization.
Any entity, regardless of roles, can see all entities from its own organization, though some sensitive information from services is filtered for non-admins.
Only a ROLE_SITE_ADMIN can assign ROLE_SITE_ADMIN and ROLE_APPROVE_ORG roles.
A ROLE_APPROVE_ORG can create a user for an organization if and only if there is no users for the organization (this is used for creating the first administrative user for an organization).
A ROLE_MMS_ADMIN can maintain MMS owned and operated by his own organization.

In this example we will focus on ROLE_USER and ROLE_ORG_ADMIN. Let us assume that an Organization (DMA) wants to grant members of the internal "E-navigation" department administrative rights in the MCP Identity Registry. In DMAs Identity Provider setup the department name is automatically added to the "permissions" attribute. So to make this mapping the current DMA administrator sets up a role mapping between the permission "E-navigation" and the role ROLE_ORG_ADMIN. Once this is done, all members of the DMA E-navigation department will have administrative rights for the DMA organization inside the Identity Registry. As noted earlier, these rights only apply inside the Identity Registry. Other services must create a similar setup with mapping of roles and permissions.

7. Terminology

Most of the terminology in this section has been taken from ISO/IEC 24760-1:2011 - A framework for identity management - Terminology and concepts

Authentication: The process of verifying the identity claimed by an entity based on its credentials.
Authorization: The process of establishing a specific entitlement that is consistent with authorization policies.
Authorization policies: Declarations that define entitlements of a security principal and any constraints related to that entitlement.
Entitlements: The actions an entity in a network is allowed to perform and the resources to which it is allowed access.
Federated identity: Is the means of linking a person’s electronic identity and attributes, stored across multiple distinct identity management systems
Identity: The set of attributes that uniquely identifies a security principal. A security principal can have many different accounts that it uses to access various applications in the network. These accounts can be identified by these applications using different attributes of this entity. For example, a user can be known in the e-mail service by an e-mail ID, whereas that same user can be known in the human resource application by an employee number. The global set of such attributes constitutes the identity of the entity.
Identity administration: The act of managing information associated with the identity of a security principal. The information can be used by the identity management infrastructure itself to determine administrative privileges.
Identity management policies: Policies affecting the management of identities which includes naming policies and security policies.
Realm: A collection of identities and associated policies which is typically used when enterprises want to isolate user populations and enforce different identity management policies for each population.
Security principals: The subjects of authorization policies, such as users, user groups, and roles. A security principal can be a human or any application entity with an identity in the network and credentials to assert the identity.

8. Appendix

The use of MCP as a login mechanism: We share our experience from PortCDM on how to utilize MCP as a login mechanism based on Keycloak; refer this Microsoft Word file.

1. Geocasting refers to the delivery of information to a group of actors identified by their geographical locations.