The License Portal gives software developers a simple and flexible way to allow users to create and manage their CmCloudContainers and activate or deactivate licenses themselves. But this degree of freedom and trust does not fit in with every software project. In such cases, these abilities should be handled by a dedicated portal or separate software, where the entire license portal, including user registration, is completely hidden from viewers. This is why the CodeMeter License Portal comes with a special REST-API for the purpose. This article takes a closer look at this API, called Gateways.
The Credential File
The License Portal and REST-API represent a simple means to communicate with CodeMeter License Central and CodeMeter Cloud. Users are given credential files with the details they need to access their CmCloudContainers. CodeMeter Cloud creates these files, but it does not store them. This is where the License Portal enters the picture: it maintains a direct one-to-one connection between a user on the Portal and a CmCloudContainer and, by implication, a credential file. Whenever a user decides to change their password, the old credential file is invalidated and a new one created. Everything happens in the background, without the user having to know what the credential file is doing for the application or the Portal. The reasons for this are psychological in nature: Users are less likely to share their passwords than their files. For even greater security, the credential file is encrypted with the user’s password.
User Accounts Required
This unbreakable link between a credential file and a user account demonstrates that License Portals and CodeMeter Cloud together can only function with user accounts. There are three options for integrating this with existing solutions:
Using the Portal’s own user admin capabilities
Creating dummy accounts for all users
Integrating with a Single-Sign-On (SSO) system
The latter option is currently handled by Wibu-Systems’ Professional Services, but is scheduled for release as a standard feature from version 22.11.
The first step in using the password is creating a user account, achieved with four parameters: “mail”, “password”, “data”, and “ticket”. The email address (“mail”) functions as a unique identifier of the user in question, which has many benefits that may outweigh the potential downsides of using email accounts for this purpose: For most users, the License Portal is something they rarely encounter, and it is unfair to expect them to remember the random name they chose for the purpose. Their email address, on the other hand, should be something they remember.
The password (“password”) should be checked in a separate client before registration, i.e. the user should have to enter it twice to double-check it. Specific rules and restrictions for passwords can also be put in place, and the system can check whether the password is compliant with those rules before the proper registration starts.
The “data” field accepts entries in any format. Its purpose is to capture additional details in the form of a Json string about the users, such as their name, age, address, shoe size etc.: Anything you want to have recorded, with only the EU GDPR regulations limiting your flexibility. The API offers an option to change or delete these entries to be fully GDPR-compliant.
The final and most interesting field is “ticket”. The License Portal can define whether a ticket from CodeMeter License Central should act as a Captcha to prevent automatic bots from creating countless spam accounts. Tickets have to be fresh by the time of registration, i.e. not yet been assigned to any other user or group. To make things easier, the ticket is automatically assigned to the user in question after the finished registration process. The captcha field can also be replaced with your own anti-spam mechanism or left out entirely.
The “register” command should ideally get the user up and running immediately. It would return a “sessionid”, the “mail”, and a “sesssiontoken”, which are then used for later API calls.
The system also informs you whether the user has to confirm with a Double-Opt-In option. This can be configured for the License Portal and would require the user to confirm a code that they are sent by email. A separate API call is used for this purpose, and the process would not continue until the user has confirmed the code.
The same “sessionid”, “mail”, and “sessiontoken” values would naturally also be returned if you connect the user by a later “login” API process. “logout” is used to end the session.
One quite popular option is for user accounts to be created automatically without the actual user having to bother with the process. This is a valid choice, but should still be handled with care to make sure that the automatically created profile is compliant with the EU GDPR data protection standards.
To create such dummy accounts, a mail address is created from the internal user ID, such as a virtual mail address on your own server; alternatively, the ticket ID could be used if users do not have an ID given to them.
A much more interesting question is the automatic creation of a password. Ideally, the system starting the registration process should be able to store a random value for each user, which could take the form of an entry in the user database, or some value on a local machine. This random value is defined, appended to the user ID, and hashed to get an automatic password.
Assigned Credential Files
A separate API call is used to get the credential file, which needs the “sessionid”, “sessiontoken”, and “mail” from the user logging in.
The password also has to be included for this purpose. Asking users again for their passwords in this manner is a good means, albeit better used sparingly to avoid irritation, to protect important functions from unauthorized use. For the License Portal, it is technically required, since the credential file is encrypted with the password.
The name of the CmCloudContainer in question can be included in this first call. This would be the name that is visible to the user in CodeMeter’s Control Center. However often it is called, this refers to the same file, even if a new name is given. To refer to the CmCloudContainer the CmActID should use the standard fixed value “3000”, which is reserved for all future purposes.
When the Portal’s user admin features are used, the client should require the password again before this API call or calculate the value accordingly in the case of dummy accounts.
A call to change the passwords needs the old and new passwords on top of the session parameters. Again, a simple precaution against accidental typos is asking the user to enter the new password twice.
This call invalidates the old credential file. When licenses in the CmCloudContainer are accessed next, they are flagged as “red” and cannot be used anymore. The user should then receive and import a new credential file with the new password.
The API is, naturally, also ready for the inevitable case that a user forgets their passwords. The process uses two specific calls: The first returns a reset token, which only needs the user’s email address and does not initiate any internal actions in the system. The reset token needs to be used in a time that you can set to your liking.
Usually, the token is sent to the email address stored in the system. It could alternatively be delivered via the API, but this calls for special attention to make sure that the API function in question can only be used by authorized applications.
The token then allows a new password to be created in a second call. This would invalidate the old credential file, which would have to be recreated and delivered with the new password.
Licenses are activated in the same manner as they are on CmDongles or in CmActLicenses: A context file is created for the CmCloudContainer by the local copy of CodeMeter and used for activation via the standard Gateway function. The update file produced in return is then uploaded again via the local CodeMeter copy, and if CodeMeter is not installed locally because the system is arranged as a SaaS solution, the License Portal API can step in as the middle man to retrieve the context file and return the update file (limited to CmCloudCIontainers).