App Installation
This topic explains how apps are installed on the AMS app framework.Learn more by watching the video
Installing apps workflow
After an app is created, an app Install Link is automatically created for that app. You can find that Install Link in the App Details page by navigating to an app.
After an app is ready to be published and distributed, this Install Link URL is distributed to users.
Note: The Install Link URL should be opened in a different browser (to avoid session conflicts).
When a user navigates to an app's Install Link URL, they will be prompted to sign into Oracle App Manager and then prompted through the installation.
After installation is complete, App Manager calls the app's install URL endpoint.
App Install URL endpoint
This endpoint is expected to be invoked by AMS on application install.
Service URL
<app-baseUrl><app-installUrl>
These URLs are registered with AMS when creating an app.
Request Method
POST
Request Header
Authorization: Bearer <JWT>
Content-Type=application/json
Bearer Token
JWT claims
When AMS is making the request to the App, the key and value pairs bear the following meanings:
| Key | Value Definition | Context |
|---|---|---|
iss
|
The issuer of the token. | The App's Token Key. |
sub
|
The subject of the token. | Set to the app's associated product uuid. |
aud
|
The audience of the token. | The App's Token Key. |
exp
|
The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. | Set to 60 seconds after the JWT was created. |
iat
|
The date and time the JWT was issued, expressed as a Unix timestamp. | Set to the current time. |
jti
|
The unique identifier for the JWT token. | Set to a random UUID |
o.a.p.ctenantId
|
The tenant Id. | Set to the id of the tenant as identified by the product |
o.a.p.cproductUUID
|
The product UUID. | Set to the UUID of the product associated with the current installation |
o.a.p.cproductName
|
The product name. | Set to the name of the product, associated with the current installation |
o.a.p.cdestinationId
|
The destination Id. | Set to the app's UUID. Found in app details. |
o.a.p.cdestinationUrl
|
The destination URL. | The destination URL is the app's base URL + the app's install URL. These URLs are found in app details. |
Signature
Signed with an app's token secret.
Sample JWT Payload
In order to authenticate with the app, AMS constructs a JWT payload using the information details about the app (e.g application uuid, application token key, product affinity, etc). AMS then sign's the JWT using the application's token secret.
Below is an example JWT payload that AMS uses to call the application install endpoint:
{
"iss": "4701447f-20f1-4a25-875f-52e36d6a93ae",
"sub": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
"aud": "4701447f-20f1-4a25-875f-52e36d6a93ae",
"exp": 1539915991,
"iat": 1539915932,
"jti": "88062cca-9b58-4391-a713-4817662526af",
"o.a.p.ctenantId": "607",
"o.a.p.cproductUUID": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
"o.a.p.cproductName": "Mock Product",
"o.a.p.csourceRequest": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
"o.a.p.cdestinationId": "c1fce274-09c5-457a-a916-141de834b4cd",
"o.a.p.cdestinationUrl": "http://localhost:8090/appInstalls/install"
}
Sample Request Body
{
"applicationInstall": {
"uuid": "4701447f-20f1-4a25-875f-52e36d6a93ae",
"deleted": 0,
"application": {
"baseUrl": "http:\/\/localhost:8090",
"configureUrl": "http:\/\/localhost:8090\/configuration.jsp",
"description": "Sample App",
"deleted": 0,
"installUrl": "appInstalls\/install",
"largeLogo": "https:\/\/images.freeimages.com\/images\/large-previews\/2fe\/butterfly-1390152.jpg",
"mediumLogo": "https:\/\/images.freeimages.com\/images\/large-previews\/2fe\/butterfly-1390152.jpg",
"name": "Sample App",
"saveConfigurationUrl": "appInstalls\/configuration",
"smallLogo": "https:\/\/images.freeimages.com\/images\/large-previews\/2fe\/butterfly-1390152.jpg",
"status": "UP",
"publicationStatus": "DEVELOPMENT",
"statusMessage": {
"body": "O",
"eta": 978309000000,
"reason": "Someone"
},
"statusUrl": "status",
"uninstallUrl": "appInstalls\/uninstall",
"uuid": "7e1da507-f54a-4a21-8ac2-cf7a8e9ae7ee",
"providerUuid": "15e2caf9-b8f1-422b-8f8c-a2936a395e0e"
},
"status": "UP"
},
"secret": "c715fdd3-5413-4e47-aa64-30cadaeb3843-6e44c5c6-6e3d-46d7-be0e-9d69f2406cbb"
}
Sample Response in case of success
The app does not need to respond to this request with any additional information. Any 2xx status code response is appropriate.
Installation URL endpoint sample code
@RequestMapping(value = "/install", method = RequestMethod.POST)
public void installApp(@RequestBody AppInstallCallDTO appInstallDto,
@RequestHeader(value = "Authorization") String authorizationHeader) {
AppInstall appInstall = convertToEntity(appInstallDto);
appInstallService.addEntity(appInstall);
}
private AppInstall convertToEntity(AppInstallCallDTO appInstallDto) {
AppInstall appInstall = modelMapper.map(appInstallDto, AppInstall.class);
appInstall.setUuid(appInstallDto.getApplicationInstall().getUuid());
return appInstall;
}
The app does not need to respond to this request with any additional information. Any 2xx status code response is appropriate.