1. Purpose of the User Guide

The purpose of this User Guide is to give instructions on how to operate the Maritime Cloud Management Portal (MC Portal). The reader is expected to be familiar with the concepts of the Maritime Cloud. For more information about the Maritime Cloud, please visit the official homepage: http://maritimecloud.net

2. General focus of the MC Portal

Everything in the MC 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 MC Portal

Icons and colors in the MC Portal follow the standard in the table:

Icon and color Function

image

Input field with validation not OK

image

Input field with validation OK

image

White button: Cancel or OK will always close the view and go back

image

Blue button: "Safe" button - no changes of the data in the Service- or Identity registry. A new page will be shown with the given functionality

image

Red button: "Unsafe" button - changes will be submitted to the data in the Service- or Identity registry

3. Not yet implemented

The Management Portal is still in early beta; thus many features are not yet implemented. If a section in this guide is "not yet implemented", but is needed or wanted, (e.g. deletion of services) please file an issue at the Github project.

4. MRN - Maritime Resource Name

Every entity in the Maritime Cloud requires an MRN. For entities in the Identity Registry (e.g. Vessels) the MRN is autogenerated following the mask:
urn:mrn:<mcl|stm>:<entity-type>:<org-shortname>:<entityID>

Example for a vessel from DMA:
urn:mrn:mcl:vessel: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 on all levels (Specification, Technical Design, Instance). The MRN will be validated though. It needs to follow the mask:
urn:mrn:<mcl|stm>:service:<service-level>:<org-shortname>:<serviceID>

Example for a service specification, technical design, instance from DMA respectively:
urn:mrn:mcl:service:specification:dma:nw-nm
urn:mrn:mcl:service:design:dma:nw-nm-rest
urn:mrn:mcl:service:instance:dma:nw-nm-rest-1

5. Login

The Martime Cloud Management Portal for the production environment can be reached at https://management.maritimecloud.net

5.1. Join the Maritime Cloud and get access to the MC Portal

To get access to the MC Portal your organization must be enrolled in the Maritime Cloud by a person who holds the legal rights to act on behalf of the organization. Please follow the "Join" link on the MC Portal login page to fill out the application form. The organization will be validated and approved by a Maritime Cloud governance organization, after which the applying organization will get access to the MC Portal.

In the test period in the EfficienSea2 and STM Validation project, the governing organization will be the Danish Maritime Authority.

5.2. Login when my organization is federated into the Maritime Cloud

When your organization is federated into the Maritime Cloud, you can use your normal organization login (probably your Windows login).

Choose your organization in the list and you will be redirected to your organization’s federated login page.

image

Once you have logged in with your organization login you will be redirected back to the MC Portal with access.

5.3. Login when my organization is part of the Project test phase (ProjectTestUsers)

When your organization is not federated, you will get access through the EfficienSea2 and STM Validation project test users.

image

Choose the "ProjectTestUsers" and provide your login information in the next page.

image

You will be redirected to the MC Portal with access.

5.4. Login to the Test environment

When using the test environment (the MC Portal for the test environment can be reached at https://test-management.maritimecloud.net) you can login using the same user as when you log into the production environment. To do this choose the "MC-production" Identity Provider when logging in.

image

This will redirect you to the login of the production environment, and you can then login as described in Login when my organization is federated into the Maritime Cloud or Login when my organization is part of the Project test phase (ProjectTestUsers).

5.5. Access Roles

The MC Portal currently has 2 different roles. Administrator with full editorial rights (for own organization only) and Member with read-only rights.

The intention is to implement a finer grained access roles - for example, admin roles for only the Identity Registry and only the Service Registry etc.

6. Managing the Identity Registry

The entities in your organizations Identity Registry can be found in the menu.

image

The following subsections will explain how each entity is managed.

6.1. My Organization

This is the "home" of the MC Portal. Here you can find various information about your own organization, like contact info, certificates (for organization level), Access Roles, etc.

6.1.1. Update contact information

To update the contact information of your organization, click the "Update" button on the "My Organization" page.

image

Make the changes and click "Update organization".

image

You can change the logo of your organization. The logo is only used in the list of organizations, which every user of the MC Portal can see. Should no logo be uploaded, a default logo will be displayed.

image

To upload a new logo, click on the logo on the "My Organization" page and browse to the new logo.

image

6.1.3. Access Roles

Not yet implemented.

6.1.4. Identity Provider information

Not yet implemented.

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

6.2.1. Create

To create a Vessel or Device, click the "+" in the list.

image

Fill out the form and click "Register Device/Vessel". The "Permissions" field is explained in depth in the Permissions section of this guide.

image

6.2.2. Update

To create a Vessel or Device, choose it in the list and click the "Update" button on the details page.

image

image

Make the changes and click "Update device".

image

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

image

6.3. Users

"Users" in this context refers to human users. Users can authenticate using the Openid Connect Identity Provider, or use a certificate issued by the Maritime Cloud.

6.3.1. Create

If an organization is federated into the Maritime Cloud, you do not need to create users!
The users will automatically be created the first time they log in on a webpage that uses Maritime Cloud, such as the MC Management Portal.

If an organization is not federated into the Maritime Cloud and is using the "ProjectTestUsers" Identity Provider, users must be created manually in the Management Portal. When the user has been created, he/she will receive an email with instructions for how to log in with a temporary password.

6.3.2. Update

Not yet implemented.

When an organization is federated into the Maritime Cloud, users are automatically created and updated when they log in on a webpage that uses Maritime Cloud, such as the MC Management Portal.

In the case that an organization is not federated into the Maritime Cloud, but is using the "ProjectTestUsers" 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 "ProjectTestUsers" Identity Provider.

6.3.3. Delete

For organizations, which is federated into the Maritime Cloud, users are automatically created or updated when they log in on a webpage that uses Maritime Cloud, such as the MC 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 the Maritime Cloud and is using the "ProjectTestUsers" Identity Provider, users can be deleted from the portal. This will also remove the user from the "ProjectTestUsers" Identity Provider. The user will no longer be able to log in to Maritime Cloud services.

When a user is deleted all of the user’s certificates are revoked.

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

For a more thorough explanation and example, please refer to the online documentation for authorization in the Maritime Cloud.

6.5. Certificates

Certificates can be issued on all entities in the Maritime Cloud (e.g. Devices, Vessels, Users, Organizations, Services). For a better understanding of how certificates is used in the Maritime Cloud and which parameters is included, please refer to the online documentation.

6.5.1. Information in the certificate

In the certificate, there are several information’s about the entity. Please refer to the online documentation.

6.5.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 "Issue new Certificate" button.

image

Click on "Issue Certificate".

image

And that is it. A certificate has been issued and is ready for download.

image

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.

6.5.3. Converting the certificate to a different format

The issued certificate is supplied in PEM (also known as PKCS #8) format, but it can easily be converted into other formats. There are several tools available that can do this, but we will recommend KeyStore Explorer which is a free, crossplatform and userfriendly tool. If you download, install and run KeyStore Explorer you will see this screen:

keystore explorer start

Click the "Create a new KeyStore" marked with the red circle. This will open a window that will let you choose the type of the new keystore. In this case we will choose JKS, which is normally used for Java applications, but you can choose a different format if needed.

keystore explorer new keystore type

You have now created an empty keystore, and now the issued client certificate must be imported into the keystore. Click the "Import Key Pair" icon marked with a red circle:

keystore explorer empty keystore

Now choose the type of the key pair to import, in this case "PKCS #8".

keystore explorer key pair type

In the new window you should click browse and choose the files for the Private Key and Certificate, respectively. Note that the "Encrypted Private Key" checkbox should be unchecked and the "Decryption Password" field should be empty.

keystore explorer select key pair

Now supply a key pair alias that will be used to find/identify the key pair in the keystore.

keystore explorer key pair alias

You will now have to enter a password for the imported keystore. This will be needed when extracting the certificate key pair from the new keystore.

keystore explorer key pair password

The key pair (private key and certificate) has now been loaded into the new keystore, and will be shown in the list. Click the "Save" icon to save the keystore to a file.

keystore explorer new keystore save1

You will know have to enter a password for the keystore itself. This will be needed when opening the keystore later.

keystore explorer keystore password

Now choose a location for your new keystore and press "Save".

keystore explorer new keystore save2

Then locate the keystore you saved, load it into your application and you should be ready to authenticate using your client certificate.

6.5.4. Revoking a certificate

When a certificate needs to be revoked, find the relevant user/vessel/device/service and the certificate that should be revoked at click on "Revoke".

certificate revoke1

This will show a window where you will have to choose a reason and a date for the revocation in the selectors. Once these has been entered you can click "Revoke".

certificate revoke2

The certificate will now have been revoked and the certificate will be marked as such in the certificate list.

certificate revoke3

7. Managing the Service Registry

The Service Registry consists of 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://maritimecloud.net or the "How To?" page in the MC Portal.

image

The following subsections will describe each level in the service registry and how to manage.

Note: At the moment, service data is shown for all organizations with no possibility to filter or search. In the future, there will be filtering and searching options. Service data for other organizations is always in read-only mode though and will never show Certificates - regardless of the user’s administrative rights.

7.1. Services Specification

7.1.1. View and download

To view a Specification, click "Specifications" in the menu and a list of specifications appear. Click on any column of a row in the list to view that Specification.

image

In the details page, you can see a subset of the Specification data. To view all data, you can download the actual documents that were uploaded upon the registration of the Specification.

image

image

7.1.2. Create/Register

To register a new Specification, click "Specifications" in the menu and a list of specifications appear. Click the "Register new Specification" button at the bottom of the list.

image

Now you can upload 2 documents (see online documentation for templates of the documents):

  • An XML-file following the official template with machine readable information. This is a required document

  • A document in human readable format of the Specification. This is not required, but it is highly recommended to provide

When the XML-file is uploaded, there will be a validation of the Specification ID, which should be a MRN (refer to the MRN - Maritime Resource Name section of this guide. An example MRN for DMA would be: urn:mrn:mcl:service:specification:dma:nw-nm

When all is uploaded correctly, click the "Register Specification" button.

image

7.1.3. Update

Not yet implemented.

7.1.4. Delete

Not yet implemented.

7.2. Service Technical Design

7.2.1. View and download

To view a Technical Design, click "Designs" in the menu and a list of Technical Designs appear. Click on any column of a row in the list to view that Design.

image

You can also get to the design by clicking any column of a row if you have a Specification in view.

image

In the details page, you can see a subset of the Technical Design data. To view all data, you can download the actual documents that were uploaded upon the registration of the Technical Design.

image

7.2.2. Create/Register

To register a new Technical Design, you need to select the Specification you want the Technical Design to implement. When the Specification is selected, you should click on the "Register new Design" at the Specification details page.

image

Now you can upload 2 documents (see online documentation for templates of the documents):

  • An Xml-file following the official template with machine readable information. This is a required document

  • A document in human readable format of the Technical Design. This is not required, but it is highly recommended to provide

When the XML-file is uploaded, there will be a validation of the Technical Design ID, which should be a MRN (refer to the MRN - Maritime Resource Name section of this guide. An example MRN for DMA would be: urn:mrn:mcl:service:design:dma:nw-nm

When all is uploaded correctly, click the "Register Design" button.

image

7.2.3. Update

Not yet implemented.

7.2.4. Delete

Not yet implemented.

7.3. Service Instance

7.3.1. View and download

To view an Instance, click "Instances" in the menu and a list of Instances appear. Click on any column of a row in the list to view that Instance.

image

You can also get to the Instance by clicking any column of a row if you have a Technical Design in view.

image

In the details page, you can see a subset of the Instance data. To view all data, you can download the actual documents that were uploaded upon the registration of the Instance.

image

7.3.2. Create/Register

To register a new Instance, you need to select the Technical Design you want the Instance to implement. When the Technical Design is selected, you should click on the "Register new Instance" at the Technical Design details page.

image

Now you can upload 2 documents (see online documentation for templates of the documents):

  • An XML-file following the official template with machine readable information. This is a required document

  • A document in human readable format of the Instance. This is not required, but it is highly recommended to provide

When the XML-file is uploaded, there will be a validation of the Instance ID, which should be a MRN (refer to the MRN - Maritime Resource Name section of this guide. An example MRN for DMA would be: urn:mrn:mcl:service:instance:dma:nw-nm

When all is uploaded correctly, you can provide additional information to the service if you should need to issue certificates for the service later. This includes the field "Certificate Domain Name", where you should enter the name of the domain where the service will be hosted (e.g. Service.dma.dk) and the field "Permissions" which will also be embedded in the certificate. Should this not be relevant for your service, simply leave the fields empty.

image

When everything is OK, click the "Register Instance" button.

7.3.3. Update

Not yet implemented

7.3.4. Delete

Not yet implemented.

7.4. Searching the Service Registry

Not yet implemented.