Skip to content
Permalink
master
Go to file
 
 
Cannot retrieve contributors at this time
643 lines (583 sloc) 20.3 KB

Federation Manager P*P


2020-08-05 20:23 JIRA FMIC-25: Fed Mgr messaging

Create and test FM message consumer(s) to read FM messages in ICP dev environment, reconcile group changes into the proper groups via Grouper API calls. Reconcile user changes into COmanage via COmanage API calls.

Consume messages consisting of outer resourceTypes:

FMperson

eventType "create":

These messages should be processed into COmanage person add actions where a person with a matching ePPN and/or email address does not exist in COmanage. The ePPN and/or email address sent in the message should be mapped into upstream / source system ePPN and email address in the new person record.

eventType "update":

These messages should be processed into COmanage person update actions where a person with a matching ePPN and/or email address already exists in COmanage. The ePPN and/or email address sent in the message should be matched with into upstream / source system ePPN and/or email address in the existing person record. Any other attributes of the existing person record present in the message should be updated with values contained in the message.

In the case where a person record does not yet exist for this person, the message should be treated as an eventType of "create".

FMrole

eventType "create"

These messages should be processed into Grouper using Grouper API calls. They should result in groups within the folder/group structure

"app:incommon:fm:(Normalized Organization Name (contained within the embedded FMorg message in the orgName field)):(roleName)"

where (roleName) is the group name within an org folder. Organization groups should be decorated with attributes for "FMorgIdentifier" and "SForgIdentifier" and these attribute values should be set for these groups based on the information contained in the embedded FMorg resourceType message. All FMperson resourceTypes contained in the embedded collection of

{ FMperson }

messages should be added to the initial population of the group.

organizationName values within embedded FMorg messages MUST be normalized by the message consumer using the following regular expression before being added to Grouper:

[^a-zA-Z0-9 _\-] (all non-alphanumeric characters should be removed)

eventType "update"

An existing group matching the full computed group path determined using the folder/group structure noted in the "create" eventType for this resourceType should be treated as the target of an update. All fields EXCEPT the FMorgIdentifier and SForgIdentifier attributes on the organization folder should be updated according to the values contained in this message and any embedded FMorg and/or FMperson resourceType messages. In the case where an existing path to a group cannot be found, the message should be treated as a "create" message and a WARN log event should be generated noting this, along with appropriate diagnostic details.

eventType "personadd"

An existing group matching the full computed group path determined using the folder/group structure noted in the "create" eventType for this resourceType should be treated as the target of this message. Any FMperson resourceType messages embedded within the message should be added to existing group membership. In the event that a group cannot be found matching the computed group path, the message should be treated as an eventType of "create" and a WARN log event should be generated noting this, along with appropriate diagnostic details.

eventType "personremove"

An existing group matching the full computed group path determined using the folder/group structure noted in the "create" eventType for this resourceType should be treated as the target of this message. Any FMperson resourceType messages embedded within the message should be removed from existing group membership. In the event that a group cannot be found matching the computed group path, the message should be treated as an eventType of "create" and a WARN log event should be generated noting this, along with appropriate diagnostic details.

FMorg

These messages are only relevant in the context of a wrapping FMrole resourceType message, for the time being.

All resourceType/eventType combinations not documented here should be silently dropped (FMperson and FMorg messages in the context of a wrapping FMrole resourceType / personadd or personremove eventType should be handled as documented above).


2020-08-03 11:18 FM messaging requirements

Bill Kaufman 11:10

Reminder @channel, Nick completed final implementer’s draft of the FM message types, thanks everyone for your feedback prior to the ICP meeting this Thursday: https://github.internet2.edu/internet2/event-msg/blob/master/fm/federation-manager-message-formats.adoc

Additionally, here are the detailed FM message consumer requirements: https://todos.internet2.edu/browse/FMIC-25 Please comment on these requirements in JIRA.

Nic Roy

Additionally, here are the detailed FM message consumer requirements: https://todos.internet2.edu/browse/FMIC-25 Please comment on these requirements in JIRA.


2020-03-10 18:06 references and links


2019-05-28 16:49 connector for fedmgr api: https://fmdev.inc.testbed.tier.internet2.edu/siteadmin/api

returnable resources

/entities
/people
/organizations/roles

next step: develop a very basic Java Spring Boot app that can accept the json object coming from the Fed Manager API and transform it to a pojo per http://www.jsonschema2pojo.org/


2019-05-17 17:45 connector for fedmgr

Federation Manager <⇒ midPoint: 1st as SoR0:00, eventually as provisioning target.

  • Initial Experiments with the Federation Manager read-only API

  • Notes on the use of API keys

    • “API keys aren’t as secure as authentication tokens (see Security of API keys), but they identify the application or project that’s calling an API.”

    • It’s a bearer token: “Because anyone who makes a request of a service transmits their key, in theory, this key can be picked up just as easy as any network transmission, and if any point in the entire network is insecure, the entire network is exposed. This makes API keys a hard thing to recommend – often misused and fundamentally insecure, they nonetheless do have their place when properly secured and hemmed in by authorization systems.”

  • Is the ConnID REST connector superclass from midPoint a good basis for developing a Federation Manager API connector? EthanK: Yes.

  • Wordpress connector is based on this superclass; See on I2 Github (Ethan)

  • midPoint provides a Dummy connector just illustrating the basic structure of a REST connector.

  • Example of a fully functional midPoint connector for Drupal using its REST API

  • midPoint’s core reference: Guide to Connector Development

  • Step 1: Understand which operations we want to do against the API, mapping to the connector functions; Understand which objects we expect to get from FM: Accounts, Organizations, Entitlements (roles)

  • Federation Manager API is read only for now

.


2019-05-17 07:09 success with fedmgr api

using Poster

https://fmdev.inc.testbed.tier.internet2.edu/siteadmin/api/organizations/roles

Content-Type	application/json
X-API-Key	0336034bd52cfadee08e9c87d20c7638


Response:
status: 200 OK
content-security-policy: script-src 'self' blob: filesystem: chrome-extension-resource:; object-src 'self' blob: filesystem:;
cache-control: no-cache
etag: "5vpNazOuDZnW54clALeRFXoa+AI="
content-type: text/html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" type="text/css" href="css/base.css" />
</head>
<body>
<div id="urlbox">
URL: <input type="text" size="70" id="url" value="http://"/>
</div>
<br />
<div id="header">
Headers: <br />
Name: <input type="text" size="15" id="header_name" value=""/>
Value: <input type="text" size="15" id="header_value" value=""/>
<input type="button" id="add_header_button" value="Add/Change"/>
<br />
value '##' to delete
<br />
<br />
<div id="header_list">
</div>
</div>
<br />
<div id="body">
Content Body:
<textarea id="content_body" rows="3" cols="60"></textarea>
</div>
<br />
<div id="actions">
<input type="button" id="get_request_button" value="GET"/>
<input type="button" id="post_request_button" value="POST"/>
<input type="button" id="head_request_button" value="HEAD"/>
<input type="button" id="put_request_button" value="PUT"/>
<input type="button" id="delete_request_button" value="DELETE"/>
</div>
<br />
Response:
<div id="response_header">
</div>
<br />
<div id="response_body">
</div>
<script src="js/popup.js"> </script>
</body>
</html>

2019-05-16 21:09 2nd attempt to work with fedmgr api

curl -X GET "https://fmdev.inc.testbed.tier.internet2.edu/siteadmin/api/organizations/roles" -H "accept: application/json" -H "X-API-Key: 0336034bd52cfadee08e9c87d20c7638" > fmRoles.adoc

curl -X GET "https://fmdev.inc.testbed.tier.internet2.edu/siteadmin/api/organizations/roles" -H "accept: application/json" -H "X-API-Key: 0336034bd52cfadee08e9c87d20c7638" > fmRoles.adoc

snippet of fmRoles.json from the successful call to the fedMgr API

{
  "data": [
    {
      "id": "1",
      "attributes": {
        "organization_id": 10002,
        "organization_name": "The Ohio State University",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000002,
        "person_name": "Scott Cantor",
        "email": "demo@example.edu"
      }
    },
    {
      "id": "14",
      "attributes": {
        "organization_id": 10014,
        "organization_name": "University of Virginia",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000015,
        "person_name": "James Jokl",
        "email": "demo@example.edu"
      }
    },
    {
      "id": "17",
      "attributes": {
        "organization_id": 10016,
        "organization_name": "Iparadigms, LLC",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000018,
        "person_name": "David Wu",
        "email": "demo@example.edu"
      }
    },
    {
      "id": "20",
      "attributes": {
        "organization_id": 10019,
        "organization_name": "Miami University",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000021,
        "person_name": "Dirk Tepe",
        "email": "demo@example.edu"
      }
    },
    {
      "id": "21",
      "attributes": {
        "organization_id": 10020,
        "organization_name": "Stanford University",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000022,
        "person_name": "Bruce Vincent",
        "email": "demo@example.edu"
      }
    },
    {
      "id": "24",
      "attributes": {
        "organization_id": 10023,
        "organization_name": "University of Rochester",
        "role": "Site administrator",
        "status": "active",
        "person_id": 1000025,
        "person_name": "Sean Singh",
        "email": "demo@example.edu"
      }
    }
  ]
}

2019-05-16 11:39 basic access to generic protected api

see agro.adoc for successful trials of another HTTP API


2019-05-16 11:39 Access to FM person repo

 Nicholas Roy:
 Hi Keith - are you OK with me getting you access to the staging instance of the FM API first?
 The data is  pretty old there, but functional.
 k:
 sure, that would be useful
 n:
 OK - I also gave your Internet2 GitHub Enterprise user account read-only access to the FM repository. The API spec is at:
 https://github.internet2.edu/InCommon/siteadmin/blob/master/api/swagger.json
 I’ll get your API key/secret and the API URL for you for staging, just a sec.
 What’s the best phone number for you to receive an activation call from Duo Security? Likely this won’t be needed, but the FM makes me supply a phone number.
 Your password, which it’s unlikely you’ll need, is `A phrase 4 a pass!`

 Your API key is: `keith-h-fm-api-testing`+
 Your API secret is: `0336034bd52cfadee08e9c87d20c7638`+
 Base API path is:
 https://fmdev.inc.testbed.tier.internet2.edu/siteadmin/api

 Let me know if you hit any issues/etc.
 {
  "swagger": "2.0",
  "info": {
    "title": "InCommon Federation Manager",
    "description": "This API provides read-only access to the InCommon Federation Manager.",
    "contact": {
      "name": "InCommon Support",
      "url": "http://www.incommon.org/",
      "email": "admin@incommon.org"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "0.0.2"
  },
  "host": "service1.internet2.edu",
  "basePath": "/api",
  "schemes": [
    "https"
  ],
  "paths": {
    "/entities": {
      "get": {
        "tags": [
          "Entities"
        ],
        "summary": "Get all entities",
        "operationId": "getEntities",
        "parameters": [
          {
            "$ref": "#/parameters/apiKeyParam"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/EntitiesResponse"
            }
          }
        }
      }
    },
    "/people": {
      "get": {
        "tags": [
          "People"
        ],
        "summary": "Get all people",
        "operationId": "getPeople",
        "parameters": [
          {
            "$ref": "#/parameters/apiKeyParam"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/PeopleResponse"
            }
          }
        }
      }
    },
    "/organizations/roles": {
      "get": {
        "tags": [
          "Roles"
        ],
        "summary": "Get all organization roles",
        "operationId": "getOrganizationsRoles",
        "parameters": [
          {
            "$ref": "#/parameters/apiKeyParam"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/OrganizationRolesResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Entity": {
      "type": "object",
      "required": [
        "id",
        "attributes"
      ],
      "properties": {
        "id": {
          "type": "string",
          "example": "1"
        },
        "attributes": {
          "type": "object",
          "required": [
            "id",
            "entity_name",
            "type",
            "organization_id",
            "organization_name",
            "status"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "entity_name": {
              "type": "string",
              "example": "https://idp.example.org/Shibboleth"
            },
            "type": {
              "type": "string",
              "example": "Entities::Idp"
            },
            "organization_id": {
              "type": "integer",
              "example": 1
            },
            "organization_name": {
              "type": "string",
              "example": "Example Organization"
            },
            "status": {
              "type": "string",
              "example": "published"
            }
          }
        }
      }
    },
    "EntitiesResponse": {
      "type": "object",
      "required": ["data"],
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Entity"
          }
        }
      }
    },
    "OrganizationRole": {
      "type": "object",
      "required": [
        "id",
        "attributes"
      ],
      "properties": {
        "id": {
          "type": "string",
          "example": "1"
        },
        "attributes": {
          "type": "object",
          "required": [
            "id",
            "organization_id",
            "firstname",
            "middlename",
            "lastname",
            "informalname",
            "email",
            "phonenumber",
            "mobilenumber",
            "faxnumber",
            "website"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "organization_id": {
              "type": "integer",
              "example": 1
            },
            "firstname": {
              "type": "string",
              "example": "J."
            },
            "middlename": {
              "type": "string"
            },
            "lastname": {
              "type": "string",
              "example": "Doe"
            },
            "informalname": {
              "type": "string"
            },
            "email": {
              "type": "string",
              "example": "jdoe@example.org"
            },
            "phonenumber": {
              "type": "string",
              "example": "(800) 555-0100"
            },
            "mobilenumber": {
              "type": "string",
              "example": "(800) 555-0100"
            },
            "faxnumber": {
              "type": "string",
              "example": "(800) 555-0100"
            },
            "website": {
              "type": "string",
              "example": "https://example.org"
            }
          }
        }
      }
    },
    "OrganizationRolesResponse": {
      "type": "object",
      "required": ["data"],
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/OrganizationRole"
          }
        }
      }
    },
    "PeopleResponse": {
      "type": "object",
      "required": ["data"],
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Person"
          }
        }
      }
    },
    "Person": {
      "type": "object",
      "required": [
        "id",
        "attributes"
      ],
      "properties": {
        "id": {
          "type": "string",
          "example": "1"
        },
        "attributes": {
          "type": "object",
          "required": [
            "id",
            "organization_id",
            "firstname",
            "middlename",
            "lastname",
            "informalname",
            "email",
            "phonenumber",
            "mobilenumber",
            "faxnumber",
            "website"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "organization_id": {
              "type": "integer",
              "example": 1
            },
            "firstname": {
              "type": "string",
              "example": "J."
            },
            "middlename": {
              "type": ["string","null"]
            },
            "lastname": {
              "type": "string",
              "example": "Doe"
            },
            "informalname": {
              "type": ["string","null"]
            },
            "email": {
              "type": "string",
              "example": "jdoe@example.org"
            },
            "phonenumber": {
              "type": ["string","null"],
              "example": "(800) 555-0100"
            },
            "mobilenumber": {
              "type": ["string","null"],
              "example": "(800) 555-0100"
            },
            "faxnumber": {
              "type": ["string","null"],
              "example": "(800) 555-0100"
            },
            "website": {
              "type": ["string","null"],
              "example": "https://example.org"
            }
          }
        }
      }
    }
  },
  "parameters": {
    "apiKeyParam": {
      "in": "header",
      "name": "X-API-Key",
      "type": "string",
      "required": true
    }
  }
}
You can’t perform that action at this time.