1. Purpose of the User Guide
The purpose of this User Guide is to give instructions on how to operate the MCP Management Portal (Previously the Maritime Cloud Management Portal). The reader is expected to be familiar with the concepts of MCP. For more information about MCP, please visit the official homepage: https://maritimeconnectivity.net
2. General focus of the MCP Management Portal
Everything in the MCP Management Portal is centered around the organization of the logged in user.
Every entity in the Identity Registry section, only has data for the users own organization.
An organization’s own entities: Vessels, Devices, Users, and Certificates are considered private and will never be shown to others.
However, the Service Registry section has the possibility to show data for services of all organizations.
Services for other organizations are always in read-only mode though and will never show Certificates - regardless of the user’s administrative rights.
2.1. Icons and colors in the MCP Management Portal
Icons and colors in the MCP Management Portal follow the standard in the table:
| Icon and color | Function |
|---|---|
|
Input field with validation not OK |
|
Blue button: will usually create or update data in the Service- or Identity registry. |
|
Red button: will most often delete data in the Service- or Identity registry |
3. MRN - Maritime Resource Name
Every entity in the Maritime Connectivity Platform requires an MRN.
For entities in the Identity Registry (e.g. Vessels) the MRN is autogenerated following the mask:
urn:mrn:mcp:entity:<org-shortname>:<entityID>
Example for a vessel from DMA:
urn:mrn:mcp:entity:dma:imo12345
For entities in the Service Registry the MRN is not autogenerated, because it’s part of the XML that is uploaded when creating or updating Services. The MRN will be validated though.
4. Login
The MCP Management Portal for the Public Demonstrator environment can be reached at https://management.maritimeconnectivity.net
4.1. Join MCP and get access to the MCP Management Portal
To get access to the MCP Management Portal your organization must be enrolled in MCP by a person who holds the legal rights to act on behalf of the organization. Please follow the "Request to join" link on the MCP Management Portal login page to fill out the application form. The organization will be validated and approved by the MCP Consortium Secretariat, after which the applying organization will get access to the MCP Management Portal.
4.2. Loging in to the MCP Management Portal
To log in to the MCP Management Portal, click the blue "Login" button
Choose the "Users" Identity Provider and provide your login information on the next page.
You will be redirected to the MCP Management Portal with access.
4.3. Access Roles
The MCP Management Portal has a number of different roles, which are based on the role hierarchy that is defined in the MIR. The Role Mappings section will go into more detail about how to manage these roles for an organization.
5. Managing the Identity Registry
The entities in your organizations Identity Registry can be found in the menu.
The following subsections will explain how each entity is managed.
5.1. Vessels & Devices
The management of Vessels and Devices is handled in the same way. Therefore, the examples in this section apply for both.
Note: the only reason for creating Vessels and Devices is if you need a certificate for the Vessel or Device concerned. Read more about management of certificates in the section Certificates.
5.1.1. Create
To create a Vessel or Device, click the "+" in the list.
Fill out the form and click "Submit". The "Permissions" field is explained in depth in the Permissions section of this guide. The "Subsidiary MRN" field is used to provide an additional MRN of the entity that it might have in another domain or context.
5.1.2. Update
To update a Vessel or Device, choose it in the list and click the "Edit" button on the details page.
Make the changes and click "Update device".
5.1.3. Delete
Warning: If you delete an entity, all issued certificates will be revoked and become invalid.
To delete click the "Delete" button on the entity you want to delete.
5.2. Users
"Users" in this context refers to human users. Users can authenticate using the Openid Connect Identity Provider, or use a certificate issued by MCP.
5.2.1. Create
If an organization is federated into MCP, you do not need to create users!
The users will automatically be created the first time they log in on a webpage that uses MCP, such as the MCP Management Portal.
If an organization is not federated into MCP and is using the "Users" Identity Provider, which is the default, users must be created manually in the Management Portal. When the user has been created, they will receive an email with instructions for how to log in with a temporary password.
5.2.2. Update
When an organization is federated into MCP, users are automatically created and updated when they log in on a webpage that uses MCP, such as the MC Management Portal.
In the case that an organization is not federated into MCP, but is using the "Users" Identity Provider, users must be updated manually in the Management Portal.
Updating the password of a user cannot be done in the portal, this must be done from the "Users" Identity Provider.
5.2.3. Delete
For organizations that are federated into MCP, users are automatically created or updated when they log in on a webpage that uses MCP, such as the MCP Management Portal. Therefore, deleting users does not make much sense for federated organizations, unless it is necessary to clean up the user list, or to remove all the users’ certificates.
If an organization is not federated into MCP and is using the "Users" Identity Provider, users can be deleted from the portal. This will also remove the user from the "Users" Identity Provider. The user will no longer be able to log in to access MCP services.
When a user is deleted all of the users certificates are revoked.
5.3. Permissions
"Permissions" is a field which service providers can use to implement a method of access control (authorization) in their services. As an example, an organization could wish to grant extended access to a service for all their pilots from a single point of control. The permissions field is a way to facilitate this.
The "Permissions" field is also used internally in the MIR to facilitate Role Based Access Control (RBAC). See Access Roles and Role Mappings for more information about this.
For a more thorough explanation and example, please refer to the online documentation for authorization in MCP.
5.4. Certificates
Certificates can be issued for all entities in the MIR. For a better understanding of how certificates are used in MCP and which parameters are included, please refer to the online documentation.
5.4.1. Information in the certificate
In the certificate, there are multiple about the entity, such as MRN, name, organization, etc. Please refer to the online documentation.
5.4.2. Issuing a certificate
On every entity details page, there is a certificate section. This section is the same component for all entities. Therefore, the description and examples applies for all.
To issue a new certificate, click on the "Add" button.
And that is it. A certificate has been issued and is ready for download.
When you download you will receive a zip file that contains public key, private key and certificate in PEM format, and the certificate in a .p12 keystore. The password for the keystore is written in a .txt file that is also contained in the zip file.
NOTE: It is very important that you download the certificate, because it is the only time, that you can download the public- and private key.
5.4.3. Revoking a certificate
When a certificate needs to be revoked, find the relevant user/vessel/device/service and the certificate that should be revoked and click on "Revoke".
This will show a window where you will have to choose a reason and a date for the revocation in the selectors. Once these have been entered you can click "Revoke".
The certificate will now have been revoked and the certificate will be marked as such in the certificate list.
5.5. Role Mappings
As mentioned in the Access Roles the MCP Management Portal and the MIR use roles to determine what users are allowed to do. This is done by mapping so-called permissions, which can be assigned to users, to one or more roles. In order to create such a role mapping, go to the "Roles" section and click on "Add".
This will show a form where you will have to choose a role that the mapping will map to and a permission that it will map from. Once these have been filled out, click on "Submit".
The newly created role mapping can now be used to assign a role to a user.
6. Managing the Service Registry
The Maritime Service Registry (MSR) is a registry where maritime stakeholders can register services for others to discover. Services can be searched for using parameters such as provider, service type, MRN and geographical coverage area.
Conceptually, the underlying G1128 standard describes a service on 3 levels:
-
Specification: Technology-agnostic logical level (What)
-
Technical Design: Technology level (How)
-
Instance: The actual service implementation (Where)
For more information of the 3 levels and how they are connected, please refer to the online documentation at http://maritimeconnectivity.net. In the MCP Management Portal, however, only the Instance level is directly managed: you register a service instance, and it optionally references the MRNs of the Specification and Technical Design it implements. Specification and Technical Design are otherwise only used as search criteria (see Searching the Service Registry).
Note: Service data is shown for all organizations with no possibility to filter by organization on the "Services" list. Service data for other organizations than your own is always shown in read-only mode, and it is never possible to issue Certificates for another organization’s services - regardless of the user’s administrative rights.
6.1. Service Instance
In the menu, the "Service Registry" section contains "Services" (the list of registered service instances) and "Search" (see Searching the Service Registry).
6.1.1. View
To view the registered Services, click "Services" in the menu and a list of Services appears. Click on any row in the list to view that Service instance.
In the details page, you can see the full set of data for the Service instance, including its geographical coverage area on a map. If the Service was registered from a G1128 XML document, you can view the raw XML via the "View XML" button next to "Instance as XML", and if a human-readable document was attached, it can be downloaded via "Instance as document".
6.1.2. Create/Register
To register a new Service instance, click "Services" in the menu and then click the "+ Add" button.
There are two ways to provide the data for the new Instance:
-
Fill in the form directly. The required fields are Name, Version, Status, Endpoint URI, Organization ID, Instance ID and Comment. The Instance ID must be a valid MRN (refer to the MRN - Maritime Resource Name section of this guide). Optionally, you can also specify a Service type, a Data product type, the MRNs of the Technical Design it implements, and draw the service’s geographical coverage area on the map. You can also attach a human-readable document describing the Instance under "Instance as document".
-
Click "Create with G1128 XML" to instead paste in a complete G1128-compliant XML description of the Instance, and click "Verify". If the XML is valid, the form fields are automatically filled in from its content, and the XML itself is stored alongside the Instance so it can be viewed later from the details page.
When all required fields are filled in (or the XML has been successfully verified), click the "Submit" button to register the Instance.
6.1.3. Update
To update a Service instance, open it from the "Services" list and click "Edit". The same form as for registration is shown, pre-filled with the current data, and you can either edit the fields directly or click "Edit with G1128 XML" to replace the data by pasting in and verifying a new G1128 XML document.
When you are done, click "Submit" to save the changes, or "Cancel" to discard them.
6.1.4. Delete
A Service instance can be deleted either from its details page by clicking "Delete", or from the "Services" list by ticking the checkbox next to one or more rows and clicking "Delete" in the toolbar.
| Deleting an Instance takes effect immediately - there is no confirmation prompt, and the action cannot be undone from the Management Portal. |
6.2. Searching the Service Registry
To search for services - including those registered by other organizations - click "Search" in the "Service Registry" menu section. The search follows the IEC 63173-2 SECOM and IALA G1191 standards.
First, choose the search scope: "Local MSR only" searches only the MSR your organization is registered with, while "Global (Includes other MSRs)" also includes results from other connected MSRs. The first time you perform a search, you may be asked to create a certificate password; this password is used to encrypt, in your browser, the certificate used to sign your SECOM search requests, and is required before any search - local or global - will return results.
When searching with "Global (Includes other MSRs)" selected, the Management Portal first shows the results from your own MSR, then queries the other connected MSRs in the background - a "Fetching additional global results…" indicator is shown while this is in progress. As results come in from other MSRs, they are added to the result list, and the "Source MSR" column shows which MSR each result came from, so you can tell local results apart from those found elsewhere.
Next, build a query by selecting a field from the "Add query" drop-down, such as Name, Status, Version, Keywords, Description, Data product type, Specification ID, Design ID, Instance ID (MRN), MMSI, IMO number, Service type, UN/LOCODE or Endpoint URI, and entering a value to match against it. Multiple query fields can be added and combined.
You can also draw a geographical area of interest directly on the map, using the drawing tools on the left of the map, to limit the search to services whose coverage area overlaps it. Once drawn, the shape is added to the query as a "Geometry" entry, alongside any other query fields you have added.
The "Presets" section offers a few ready-made example queries to get started with.
Once your query is ready, click "Search" to run it, or "Clear all" to reset the form. Search results are listed below the map; clicking a result opens it in read-only view, with a "Move to Detail Page" button that becomes available when the result belongs to your own organization, taking you to the full editable details page for that Instance.